PeekPanda markpeekpandaDocumentation
For your AI
Copy pageCopy entire docs
Dashboard

Analyze paid-ad creative

Ask for creative analysis of one stored ad’s owned media; it runs in the background.

Download Markdown ↓

POSThttps://api.peekpanda.com/v1/paid-ads/{platform}/{archiveId}/analysis

Request

The command has no request body and answers 202 at once: it stores the request and a background worker runs it, usually within a minute. Read where it stands with GET /v1/paid-ads/{platform}/{archiveId}/analysis every 15 to 30 seconds until status is ready or failed; each read counts toward the daily API and MCP call allowance. Asking again while it runs returns the same pending request, and a ready analysis is returned from storage without another run. A video analysis stored before timelines is regenerated to add one, and the stored analysis stays if that fails. It accepts mirrored image or video media up to 25 MB. For a video, the same run also generates and stores the transcript when it is missing; read it from GET /v1/paid-ads/{platform}/{archiveId}. A transcript that fails, or a video with no speech, does not fail the analysis.

Parameters

NameInTypeRequiredDescription
platformpathmeta | tiktokYesAdvertising platform.
archiveIdpathstring, 1–255YesProvider archive id.

Response

Returns the analysis state: pending with requestedAt while the worker runs it, or ready with the stored analysis when one already exists.

Response fields

statusstring
requestedAtstring

Authentication

Requires Bearer API credential or OAuth access token. Scope content:write. MCP calls refresh with action ad_analysis.

Errors

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

MCP request

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

{
  "name": "refresh",
  "arguments": {
    "request": {
      "action": "ad_analysis",
      "params": {
        "platform": "<platform>",
        "archiveId": "<archiveId>"
      }
    }
  }
}

Source

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

Refresh

An explicit request uses the owned mirror and persists its result. Repeating after settlement returns the stored result without generating it again.

AI agent or LLM? Read this page as markdown