# Get submission analytics

Returns read-only submission analytics with normalized metrics and money streams.
Only accessible by the submission creator.
Supports from, to, and bucket for date range and bucketing (defaults apply when omitted).
All timestamps are in UTC (ISO 8601 format with Z suffix).

Endpoint: GET /submissions/{submissionId}/analytics
Version: 0.1.0
Security: bearerAuth

## Path parameters:

  - `submissionId` (string, required)
    Unique identifier for the submission
    Example: "submission_abc123"

## Query parameters:

  - `from` (string)
    ISO timestamp (inclusive) for analytics window start (UTC)
    Example: "2024-01-01T00:00:00Z"

  - `to` (string)
    ISO timestamp (exclusive) for analytics window end (UTC)
    Example: "2024-01-15T00:00:00Z"

  - `bucket` (string)
    Bucket granularity override
    Enum: "DAY", "WEEK"

## Response 200 fields (application/json):

  - `submission_id` (string, required)
    Unique identifier for the submission
    Example: "submission_abc123"

  - `participation_id` (string, required)
    Unique identifier for the participation
    Example: "participation_xyz789"

  - `campaign_id` (string, required)
    Unique identifier for the campaign
    Example: "campaign_abc123"

  - `platform` (string, required)
    Platform type for the submission
    Enum: "INSTAGRAM", "TIKTOK", "FACEBOOK", "YOUTUBE"

  - `content_url` (string, required)
    Original content URL submitted by the creator
    Example: "https://instagram.com/p/example"

  - `status` (string, required)
    Enum: "ACCEPTED", "REJECTED", "PENDING"

  - `metrics` (object, required)

  - `metrics.totals` (object, required)

  - `metrics.totals.impressions` (integer,null, required)
    Example: 12345

  - `metrics.totals.reach` (integer,null, required)
    Example: 9000

  - `metrics.totals.likes` (integer,null, required)
    Example: 320

  - `metrics.totals.comments` (integer,null, required)
    Example: 44

  - `metrics.totals.shares` (integer,null, required)

  - `metrics.totals.saves` (integer,null, required)
    Example: 12

  - `metrics.totals.views` (integer,null, required)

  - `metrics.timeseries` (object, required)

  - `metrics.timeseries.bucket` (string, required)
    Bucket granularity for timeseries aggregation.
    Enum: "DAY", "WEEK"

  - `metrics.timeseries.series` (array, required)

  - `metrics.timeseries.series.metric` (string, required)
    Normalized Varmply metric key.
    Enum: "impressions", "reach", "likes", "comments", "shares", "saves", "views"

  - `metrics.timeseries.series.points` (array, required)

  - `metrics.timeseries.series.points.start_at` (string, required)
    Start of the aggregation window (inclusive, UTC)
    Example: "2024-01-01T00:00:00Z"

  - `metrics.timeseries.series.points.end_at` (string, required)
    End of the aggregation window (exclusive, UTC)
    Example: "2024-01-02T00:00:00Z"

  - `metrics.timeseries.series.points.value` (integer,null, required)
    Value for the metric in this window (null if unavailable)
    Example: 1000

  - `metrics.timeseries.series.points.is_partial` (boolean, required)
    True if derived from an incomplete window (e.g. range cuts a bucket boundary)

  - `metrics.timeseries.series.points.source` (string, required)
    Source of the chart point value.
    Enum: "SNAPSHOT_DELTA", "PLATFORM_TOTAL", "ESTIMATED"

  - `money` (object, required)

  - `money.accrued_cents` (integer, required)
    Example: 120000

  - `money.paid_cents` (integer, required)
    Example: 80000

  - `money.blocked_cents` (integer, required)
    Example: 40000

  - `money.blocked_reason_code` (string,null, required)
    Reason code for blocked accruals (null when blocked_cents is 0)
    Enum: "INSUFFICIENT_ESCROW"

  - `freshness` (object, required)

  - `freshness.status` (string, required)
    Metrics status
    Enum: "OK", "STALE", "FAILED", "PENDING"

  - `freshness.last_snapshot_at` (string,null, required)
    Timestamp of the most recent snapshot fetchedAtTimestamp (UTC)
    Example: "2024-01-01T12:00:00Z"

  - `freshness.last_attempt_at` (string,null, required)
    Timestamp of the most recent ingestion attempt (UTC)
    Example: "2024-01-01T12:10:00Z"

  - `freshness.last_success_at` (string,null, required)
    Timestamp of the most recent successful ingestion (UTC)
    Example: "2024-01-01T12:00:00Z"

  - `freshness.last_failure_reason` (string,null, required)
    Last failure reason mapped into a stable enum (null if none)
    Enum: "RATE_LIMIT", "PERMISSION", "INVALID_MEDIA", "UNKNOWN"

  - `freshness.freshness_status` (string, required)
    Freshness status of the analytics data
    Enum: "FRESH", "STALE", "UNKNOWN"

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code that identifies the type of error. This is a stable identifier that can be used
for programmatic error handling. Common codes include:
- NOT_FOUND - Resource not found
- VALIDATION_ERROR - Input validation failed
- PERMISSION_DENIED - User lacks permission for the action
- CONFLICT - Request conflicts with current resource state
- UNAUTHORIZED - Authentication required
- INTERNAL_SERVER_ERROR - Unexpected server error
    Example: "VALIDATION_ERROR"

  - `message` (string, required)
    User-friendly error message that should always be displayed to end users. This message is
designed to be clear, actionable, and free of technical details.

This field is always present and contains the primary message for end users.
    Example: "The email address you entered is not valid. Please check the format and try again."

  - `technicalMessage` (string)
    Optional technical message for developers. Contains detailed information including IDs,
error codes, and technical context. Only included when it differs from the user-friendly
message field. When present, developers can use this for debugging while end users
should see the message field.
    Example: "Campaign with ID campaign_123 not found"

  - `details` (object)
    Additional error details (optional). May contain structured information about the error,
such as validation field errors or additional context.

  - `requestId` (string)
    Unique request identifier for tracing. Included in X-Request-ID header and can be used
to correlate errors with server logs.
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `timestamp` (string, required)
    ISO 8601 timestamp when the error occurred
    Example: "2024-01-01T00:00:00Z"

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code that identifies the type of error. This is a stable identifier that can be used
for programmatic error handling. Common codes include:
- NOT_FOUND - Resource not found
- VALIDATION_ERROR - Input validation failed
- PERMISSION_DENIED - User lacks permission for the action
- CONFLICT - Request conflicts with current resource state
- UNAUTHORIZED - Authentication required
- INTERNAL_SERVER_ERROR - Unexpected server error
    Example: "VALIDATION_ERROR"

  - `message` (string, required)
    User-friendly error message that should always be displayed to end users. This message is
designed to be clear, actionable, and free of technical details.

This field is always present and contains the primary message for end users.
    Example: "The email address you entered is not valid. Please check the format and try again."

  - `technicalMessage` (string)
    Optional technical message for developers. Contains detailed information including IDs,
error codes, and technical context. Only included when it differs from the user-friendly
message field. When present, developers can use this for debugging while end users
should see the message field.
    Example: "Campaign with ID campaign_123 not found"

  - `details` (object)
    Additional error details (optional). May contain structured information about the error,
such as validation field errors or additional context.

  - `requestId` (string)
    Unique request identifier for tracing. Included in X-Request-ID header and can be used
to correlate errors with server logs.
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `timestamp` (string, required)
    ISO 8601 timestamp when the error occurred
    Example: "2024-01-01T00:00:00Z"

## Response 403 fields (application/json):

  - `error` (string, required)
    Error code that identifies the type of error. This is a stable identifier that can be used
for programmatic error handling. Common codes include:
- NOT_FOUND - Resource not found
- VALIDATION_ERROR - Input validation failed
- PERMISSION_DENIED - User lacks permission for the action
- CONFLICT - Request conflicts with current resource state
- UNAUTHORIZED - Authentication required
- INTERNAL_SERVER_ERROR - Unexpected server error
    Example: "VALIDATION_ERROR"

  - `message` (string, required)
    User-friendly error message that should always be displayed to end users. This message is
designed to be clear, actionable, and free of technical details.

This field is always present and contains the primary message for end users.
    Example: "The email address you entered is not valid. Please check the format and try again."

  - `technicalMessage` (string)
    Optional technical message for developers. Contains detailed information including IDs,
error codes, and technical context. Only included when it differs from the user-friendly
message field. When present, developers can use this for debugging while end users
should see the message field.
    Example: "Campaign with ID campaign_123 not found"

  - `details` (object)
    Additional error details (optional). May contain structured information about the error,
such as validation field errors or additional context.

  - `requestId` (string)
    Unique request identifier for tracing. Included in X-Request-ID header and can be used
to correlate errors with server logs.
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `timestamp` (string, required)
    ISO 8601 timestamp when the error occurred
    Example: "2024-01-01T00:00:00Z"

## Response 404 fields (application/json):

  - `error` (string, required)
    Error code that identifies the type of error. This is a stable identifier that can be used
for programmatic error handling. Common codes include:
- NOT_FOUND - Resource not found
- VALIDATION_ERROR - Input validation failed
- PERMISSION_DENIED - User lacks permission for the action
- CONFLICT - Request conflicts with current resource state
- UNAUTHORIZED - Authentication required
- INTERNAL_SERVER_ERROR - Unexpected server error
    Example: "VALIDATION_ERROR"

  - `message` (string, required)
    User-friendly error message that should always be displayed to end users. This message is
designed to be clear, actionable, and free of technical details.

This field is always present and contains the primary message for end users.
    Example: "The email address you entered is not valid. Please check the format and try again."

  - `technicalMessage` (string)
    Optional technical message for developers. Contains detailed information including IDs,
error codes, and technical context. Only included when it differs from the user-friendly
message field. When present, developers can use this for debugging while end users
should see the message field.
    Example: "Campaign with ID campaign_123 not found"

  - `details` (object)
    Additional error details (optional). May contain structured information about the error,
such as validation field errors or additional context.

  - `requestId` (string)
    Unique request identifier for tracing. Included in X-Request-ID header and can be used
to correlate errors with server logs.
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `timestamp` (string, required)
    ISO 8601 timestamp when the error occurred
    Example: "2024-01-01T00:00:00Z"

## Response 503 fields (application/json):

  - `error` (string, required)
    Error code that identifies the type of error. This is a stable identifier that can be used
for programmatic error handling. Common codes include:
- NOT_FOUND - Resource not found
- VALIDATION_ERROR - Input validation failed
- PERMISSION_DENIED - User lacks permission for the action
- CONFLICT - Request conflicts with current resource state
- UNAUTHORIZED - Authentication required
- INTERNAL_SERVER_ERROR - Unexpected server error
    Example: "VALIDATION_ERROR"

  - `message` (string, required)
    User-friendly error message that should always be displayed to end users. This message is
designed to be clear, actionable, and free of technical details.

This field is always present and contains the primary message for end users.
    Example: "The email address you entered is not valid. Please check the format and try again."

  - `technicalMessage` (string)
    Optional technical message for developers. Contains detailed information including IDs,
error codes, and technical context. Only included when it differs from the user-friendly
message field. When present, developers can use this for debugging while end users
should see the message field.
    Example: "Campaign with ID campaign_123 not found"

  - `details` (object)
    Additional error details (optional). May contain structured information about the error,
such as validation field errors or additional context.

  - `requestId` (string)
    Unique request identifier for tracing. Included in X-Request-ID header and can be used
to correlate errors with server logs.
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `timestamp` (string, required)
    ISO 8601 timestamp when the error occurred
    Example: "2024-01-01T00:00:00Z"