# Get paid ad

Read one stored paid-ad observation with its matched listing and the ads around it.

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

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

## 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

Identify the ad with the platform and archive id carried in its canonicalKey. This read returns stored observations and never collects new ads.

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

## MCP request

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

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

```

## Response

item is the stored observation. product is the matched iOS listing, or null when the ad carries no verified store link. sameAppAds holds up to six further stored ads of the app the ad belongs to, latest start first with undated ads last, and otherAppAds up to six of the newest ads of other apps. transcript and analysis are null until they have been collected. The route answers 404 when no stored ad matches the identity.

```
{
  "item": {
    "id": "33333333-3333-4333-8333-333333333333",
    "canonicalKey": "paid:meta:111222333",
    "source": "paid",
    "platform": "meta",
    "archiveId": "111222333",
    "advertiser": {
      "externalId": "444555666",
      "name": "Example Advertiser"
    },
    "status": "active",
    "startedAt": "2026-08-01T00:00:00.000Z",
    "endedAt": null,
    "discoveredAt": "2026-09-06T00:00:00.000Z",
    "sourceUrl": "https://www.facebook.com/ads/library?id=111222333",
    "creative": {
      "format": "video",
      "hook": "Turn saved recipes into a grocery list",
      "body": "Turn saved recipes into a grocery list.",
      "title": "Example Meal Planner",
      "description": null,
      "ctaText": "Download",
      "imageUrls": [
        "https://cdn.example.com/ad.jpg"
      ],
      "videoUrls": [
        "https://cdn.example.com/ad.mp4"
      ],
      "units": []
    },
    "productLink": {
      "kind": "official_domain",
      "name": "Example Meal Planner",
      "url": "https://example.com",
      "externalId": null,
      "confidence": "unresolved"
    },
    "destination": {
      "kind": "web",
      "url": "https://example.com",
      "host": "example.com",
      "page": "example.com",
      "appStoreId": null
    },
    "productIconUrl": null,
    "performance": {
      "kind": "unavailable"
    },
    "saved": false
  },
  "product": null,
  "sameAppAds": [],
  "otherAppAds": [],
  "transcript": null,
  "analysis": null
}

```

## Source

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

## Refresh

This read returns stored observations. Saving an ad changes boards only.