# Get Ad Detail

Fetches one ad's full disclosed creative, advertiser, targeting, reach, placement, and delivery detail by ad id.

- Platform: [TikTok Ad Library](https://docs.upscrape.com/docs/platforms/tiktok-adlibrary)
- Capability ID: `tiktok-adlibrary.ad.detail.get`
- Cost: 10 credits per request
- Maximum runtime: 120 seconds
- Execute endpoint: `POST https://data.upscrape.com/execute`

## Request

Use the exact public capability ID in the shared execute envelope.

```bash
curl --request POST \
  --url https://data.upscrape.com/execute \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Prefer: wait=30" \
  --data '{
  "input": {
    "ad_id": "1870908557528450"
  },
  "capability": "tiktok-adlibrary.ad.detail.get"
}'
```

## Input

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ad_id` | `string` | Yes | TikTok Commercial Content Library ad id returned by ad.search or advertiser-ads.list. |

### Example input

```json
{
  "ad_id": "1870908557528450"
}
```

## Response

Successful output is returned in `results[0].data`. Raw platform output is intentionally open-ended and may evolve with the upstream source.

### Illustrative sample output

This redacted fixture is an example, not a fixed response schema.

```json
{
  "ad": {
    "advertising_objective": "Reach",
    "audit_status": "1",
    "estimated_audience": "1K-10K",
    "first_shown_date": 1784160000000,
    "id": "1870908557528450",
    "image_urls": [
      "https://p19-common-sign.tiktokcdn.com/tos-useast2a-i-photomode-euttp/6fe919413e04491ebaad8b42f3b28f2e~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=[redacted:credential]&x-expires=1787421600&x-signature=[redacted:credential]&t=4d5b0474&ps=13740610&shp=0c75dd76&shcp=9b759fb9&idc=sg1",
      "https://p16-common-sign.tiktokcdn.com/tos-useast2a-i-photomode-euttp/b49835fb967d42d78df3607de90a33c0~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=[redacted:credential]&x-expires=1787421600&x-signature=[redacted:credential]&t=4d5b0474&ps=13740610&shp=0c75dd76&shcp=9b759fb9&idc=sg1",
      "https://p16-common-sign.tiktokcdn.com/tos-useast2a-i-photomode-euttp/f7a12687beda49b3b6cb8b2384970e8a~tplv-tiktokx-origin.jpeg?dr=14582&refresh_token=[redacted:credential]&x-expires=1787421600&x-signature=[redacted:credential]&t=4d5b0474&ps=13740610&shp=0c75dd76&shcp=9b759fb9&idc=sg1"
    ],
    "impression": 0,
    "last_shown_date": 1784246400000,
    "name": "elenouillee.57",
    "rejection_info": null,
    "show_mode": 2,
    "sor_audit_status": "1",
    "spent": "",
    "type": "2",
    "videos": []
  },
  "advertiser": {
    "adv_biz_ids": "7486037071044411408",
    "name": "elenouillee.57",
    "registry_location": "France",
    "sponsor": "7486037098525360150",
    "tt_user": null
  },
  "display_mode": "enhanced",
  "targeting": {
    "age": [
      {
        "13-17": true,
        "18-24": true,
        "25-34": true,
        "35-44": true,
        "45-54": true,
        "55+": true,
        "region": "FR"
      }
    ],
    "audience": "No",
    "audience_exclude": "No",
    "cities": [],
    "countries": [
      "FR"
    ],
    "creator_interactions": "",
    "device_models": [],
    "gender": [
      {
        "female": true,
        "male": true,
        "region": "FR",
        "unknown": true
      }
    ],
    "high_spending_power": "No",
    "interest": "",
    "languages": [],
    "location": {
      "data": [
        {
          "breakdowns": [
            {
              "age": "13-17",
              "gender": "MALE",
              "impressions": "0-1K"
            },
            {
              "age": "13-17",
              "gender": "FEMALE",
              "impressions": "0-1K"
            },
            {
              "age": "13-17",
              "gender": "UNKNOWN",
              "impressions": "0-1K"
            }
          ],
          "impressions": "2K",
          "region": "FR"
        }
      ],
      "total_impressions": "1K-10K",
      "total_region": 1
    },
    "operating_systems": [
      "ALL"
    ],
    "provinces": [],
    "target_audience_size": "22.8M-27.8M",
    "video_interactions": ""
  }
}
```
### Illustrative output fields

Derived from the sample above for orientation only. These fields are not a fixed response schema.

| Path | Observed type | Example |
| --- | --- | --- |
| `ad` | `object` | 15 fields |
| `ad.advertising_objective` | `string` | Reach |
| `ad.audit_status` | `string` | 1 |
| `ad.estimated_audience` | `string` | 1K-10K |
| `ad.first_shown_date` | `integer` | 1784160000000 |
| `ad.id` | `string` | 1870908557528450 |
| `ad.image_urls` | `array` | 3 items |
| `ad.impression` | `integer` | 0 |
| `ad.last_shown_date` | `integer` | 1784246400000 |
| `ad.name` | `string` | elenouillee.57 |
| `ad.rejection_info` | `null` | null |
| `ad.show_mode` | `integer` | 2 |
| `ad.sor_audit_status` | `string` | 1 |
| `ad.spent` | `string` |  |
| `ad.type` | `string` | 2 |
| `ad.videos` | `array` | 0 items |
| `advertiser` | `object` | 5 fields |
| `advertiser.adv_biz_ids` | `string` | 7486037071044411408 |
| `advertiser.name` | `string` | elenouillee.57 |
| `advertiser.registry_location` | `string` | France |
| `advertiser.sponsor` | `string` | 7486037098525360150 |
| `advertiser.tt_user` | `null` | null |
| `display_mode` | `string` | enhanced |
| `targeting` | `object` | 16 fields |
| `targeting.age` | `array` | 1 items |
| `targeting.audience` | `string` | No |
| `targeting.audience_exclude` | `string` | No |
| `targeting.cities` | `array` | 0 items |
| `targeting.countries` | `array` | 1 items |
| `targeting.creator_interactions` | `string` |  |
| `targeting.device_models` | `array` | 0 items |
| `targeting.gender` | `array` | 1 items |
| `targeting.high_spending_power` | `string` | No |
| `targeting.interest` | `string` |  |
| `targeting.languages` | `array` | 0 items |
| `targeting.location` | `object` | 3 fields |
| `targeting.operating_systems` | `array` | 1 items |
| `targeting.provinces` | `array` | 0 items |
| `targeting.target_audience_size` | `string` | 22.8M-27.8M |
| `targeting.video_interactions` | `string` |  |

## Execution behavior

A `200` response completed inline. A `202` response was queued; poll `GET /jobs/{id}` until the job reaches `completed` or `failed`. Use an `Idempotency-Key` when retrying must not create a duplicate logical job.

## Related documentation

- [Authentication](https://docs.upscrape.com/docs/api/authentication)
- [Jobs and results](https://docs.upscrape.com/docs/api/jobs)
- [Errors and retries](https://docs.upscrape.com/docs/api/errors)
- [Idempotency](https://docs.upscrape.com/docs/api/idempotency)