# Get paid-ad analysis

Read where one ad’s creative analysis stands, and the analysis once it is ready.

## Endpoint: GET /v1/paid-ads/{platform}/{archiveId}/analysis

- Method: `GET`
- Path: `/v1/paid-ads/{platform}/{archiveId}/analysis`
- Authentication: Bearer API credential or OAuth access token
- Required scope: `context:read`
- MCP tool: `get_ads`
- MCP action: `analysis`

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `platform` | path | meta | tiktok | yes | Advertising platform. |
| `archiveId` | path | string, 1–255 | yes | Provider archive id. |

## Known errors

- 400 invalid_request for an invalid filter, identity or limit.
- 401 authentication_required for a missing or invalid credential.
- 402 subscription_required when access is not entitled.
- 403 authorization_required for a missing scope or unavailable preview access.
- 403 workspace_not_accessible when x-genviral-tenancy names a workspace the credential cannot reach.
- 404 not_found when the record is outside the accessible catalogue.
- 429 rate_limited; honor Retry-After when present.
- 429 daily_call_limit; the plan's daily API and MCP calls are used until 00:00 UTC.

## Request

This read never starts an analysis. status is not_requested when nobody has asked, pending while the worker runs it, ready with the persisted analysis and its generation-time provenance, or failed with failedAt when the last run produced nothing; ask again with POST to retry. Treat creative observations as analysis, not a performance or policy claim.

```
curl --get 'https://api.peekpanda.com/v1/paid-ads/meta/111222333/analysis' \
  --header "Authorization: Bearer $PEEKPANDA_TOKEN" \
  --header 'x-genviral-tenancy: personal'
```

## MCP request

Call get_ads with action analysis. Path fields go in params, filters in query, and a write body in body.

```
{
  "name": "get_ads",
  "arguments": {
    "request": {
      "action": "analysis",
      "params": {
        "platform": "<platform>",
        "archiveId": "<archiveId>"
      }
    }
  }
}

```

## Response

Returns the analysis state.

```
{
  "status": "ready",
  "analysis": {
    "summary": "A concise product demonstration with a utility-first opening.",
    "visibleText": [
      "Turn saved recipes into a grocery list"
    ],
    "hookNotes": [
      "Opens with the customer outcome before showing the product."
    ],
    "timestampNotes": [
      {
        "timestampSeconds": 0,
        "note": "The app result appears immediately."
      }
    ],
    "timeline": {
      "durationSeconds": 17,
      "format": "product demo",
      "pace": "medium",
      "cutCount": 1,
      "productAppearsAtSeconds": 0,
      "scenes": [
        {
          "startSeconds": 0,
          "endSeconds": 4,
          "description": "The finished grocery list fills the screen."
        },
        {
          "startSeconds": 4,
          "endSeconds": 17,
          "description": "A saved recipe becomes a grocery list."
        }
      ],
      "onScreenText": [
        {
          "startSeconds": 0,
          "endSeconds": 4,
          "text": "Turn saved recipes into a grocery list"
        }
      ]
    },
    "editingPattern": "Fast product demonstration with direct onscreen text.",
    "reusablePromptIngredients": [
      "utility-first hook",
      "product demonstration"
    ],
    "model": "analysis-model",
    "generatedAt": "2026-09-06T00:00:00.000Z"
  }
}

```

## Source

Stored public advertising-library observations with source dates. Spend is unavailable unless the public record reports it.

## Refresh

This read returns the stored state and does not begin analysis.