# Look up an advertiser profile

> For the complete documentation index, see [llms.txt](https://www.shortsintel.com/llms.txt). Every docs page is also available as markdown: add .md to its URL. To connect, read [agents.md](https://www.shortsintel.com/agents.md).

GET `/v1/advertisers/{library}/{id}`

One advertiser's profile in one shape on every library: `id`, `url`, `ad_counts`, `linked_accounts`, `domains` and freshness, library-only fields under `extras`.

Meta

- Profile: name, Page URL, running and total Ad counts and `last_observed_at`.
- Linked accounts: Instagram account and Creator, only when Meta shows the link.
- Fresh lookup: reads and stores every Ad (every status and country) with a Snapshot. Reading to the end stamps the counts.
- Stored results: for 6 hours after that, the profile and any `advertiser` search on it are served from storage, saying `cached` and `as_of`.
- Large advertisers: one with more Ads than a lookup reads keeps its last complete counts (or Meta's total).
- No Ads in the library: 404 `not_found`, free.

TikTok

- Profile: TikTok account, registry location, paid by and counts (running: active, shown in the past 3 days). Its Ads are stored and archived.
- Complete observation: unless the library broke it off part-way; a `truncated` read, normal for a busy advertiser, counts.
- Unobserved id: a free 404 `not_found`. Pass its library URL or name.

Google

- Profile: name, `url`, `domains` when known and `ad_counts.estimate` (Google's own; `running` and `total` null), read live.
- Target: a domain, or a name several carry, is a free 409 `advertiser_ambiguous`.

[Open in Playground](https://www.shortsintel.com/console/playground?op=getLibraryAdvertiser&library=meta&id=100064000000001) (no API Key needed)

## Price

15 credits, the same when served within 6 hours of a complete observation.

Supports `estimate=true`: the reply is the price in Credits and whether it would be `cached`, with no Run created and nothing charged.

A cached result costs the same as a fresh one; `cached` says which you got.

## Parameters

| Name | In | Type | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| `library` | path | `string` one of `meta`, `tiktok`, `google` | Required | — | `meta`, `tiktok` or `google`. |
| `id` | path | `string` | Required | — | Meta: the numeric Facebook Page id (from a name or Page URL, search with `advertiser` first). TikTok: an advertiser id, library URL or name; several matches 409 `advertiser_ambiguous`, none 404. Google: an `AR` id, Transparency URL or name. |
| `wait` | query | `integer` min 0; max 120 | Optional | `30` | Seconds to hold the response open before handing back a running Run to poll. Default 30, max 120. A POST may send it in the body instead; different values in both places are a 400. |
| `max_credits` | query | `integer` min 0 | Optional | — | Most Credits the call may cost. A higher quote is a 402 `max_credits_exceeded`, no Run. Where `x-price.max_credits` is null, the Run stops at it and settles `partial`. |
| `estimate` | query | `boolean` | Optional | — | `true` returns `{ estimate_credits, cached }` from what is already stored, creating no Run. Nothing is charged. If a source the call would read is unavailable and the cache cannot answer, the estimate adds `unavailable` (the `{ platform, capability }` parts it cannot reach), or is a 503 `source_unavailable` when it can reach none. Only `true` or `false`, else a 400. A POST may send it in the body instead; different values in both places are a 400. |
| `Idempotency-Key` | header | `string` | Optional | — | 1-255 printable ASCII characters. The same key and payload returns the original Run (202 while running); a different payload or operation is a 409 `idempotency_conflict`. |

## Responses

### 200 OK

The Run finished inside the wait budget: `{ run, result }`. With `estimate=true`, `{ estimate_credits, cached }` instead.

any of 2 shapes

- Option 1 object The envelope every charged operation answers with: `{ run }` while the Run is running (plus `poll_url` on the 202), joined by `result` once it completes or `error` once it fails.
  - `run` object required Every charged operation creates a Run; the envelope is the same inline or polled.
    - `id` string required
    - `kind` string required What was run, e.g. `video_lookup`.
    - `status` string required one of `running`, `completed`, `partial`, `failed` `partial` keeps the completed items and charges for them, up to what the Balance covers; `failed` charges nothing.
    - `created_at` string required RFC 3339.
    - `completed_at` string required nullable Null while the Run is still running.
    - `charge_credits` integer required What this Run actually cost, in Credits. A stored answer costs the same as a fresh one.
    - `list_price_credits` integer required The full price of the work asked for, in Credits. Equal to `charge_credits` unless the Run charged for only part of it.
    - `cached` boolean required True when a stored result answered without a fresh fetch.
    - `progress` object A running Research's `stage` and counts so far, such as `analysed` of `shortlisted`; a count is absent until known. Absent once the Run settles and on other kinds.
      - `stage` string required one of `keywords`, `searching`, `reading_creators`, `filtering`, `analysing`, `writing_digest`
      - `keywords` integer value at least 0
      - `creators` integer value at least 0
      - `creators_read` integer value at least 0
      - `searches` integer value at least 0
      - `found` integer value at least 0
      - `judged` integer value at least 0
      - `kept` integer value at least 0
      - `dropped_off_topic` integer value at least 0
      - `dropped_unsure` integer value at least 0
      - `shortlisted` integer value at least 0
      - `analysed` integer value at least 0
      - `updated_at` string required
  - `result` object required
    - `library` string required one of `meta`, `tiktok`, `google`
    - `id` string required Its id in the library: Meta Page id, TikTok advertiser id or Google `AR` id.
    - `name` string required nullable
    - `url` string required nullable Its library page (Meta: the Page's Ad Library page). TikTok: null until its name is known.
    - `ad_counts` object required Meta, TikTok: running and total Ads as last observed, null until a complete observation. Google: `estimate` only, Google's own.
      - `running` integer required nullable
      - `total` integer required nullable
      - `estimate` integer required nullable
    - `linked_accounts` array of object required Meta's linked Instagram, TikTok's TikTok account. Empty when the library shows none; never guessed.
      - `platform` string required one of `instagram`, `tiktok`
      - `handle` string required nullable Null, with `url`, only when neither the library nor the Creator names it.
      - `url` string required nullable
      - `display_name` string required nullable
      - `followers` number required nullable
      - `verified` boolean required nullable
      - `creator_id` string required nullable Our Creator behind the account, when we hold one.
    - `domains` array of string required Domains its newest Ads serve; empty where none are reported.
    - `first_seen_at` string required
    - `last_observed_at` string required nullable When every Ad of the advertiser was last read in one go.
    - `cached` boolean required True when served from a complete observation under 6 hours old. Google: always false.
    - `as_of` string required When this profile was observed.
    - `extras` object required Exactly one key: the advertiser's library.
      - `meta` object
      - `tiktok` object
        - `registry_location` string required nullable
        - `paid_by` string required nullable
      - `google` object
    - `page_id` string Deprecated: use `id`. Meta only.
    - `page_url` string nullable Deprecated. The Facebook Page itself; `url` is its Ad Library page. Meta only.
    - `instagram` object nullable Deprecated: use `linked_accounts`. Meta only.
      - `handle` string required
      - `url` string required
    - `advertiser_id` string Deprecated: use `id`. TikTok, Google.
    - `tiktok_account` object nullable Deprecated: use `linked_accounts`. TikTok only.
    - `creator` object nullable Deprecated: use `linked_accounts[].creator_id`. Meta, TikTok.
      - `id` string required
      - `platform` string required one of `instagram`, `tiktok`
      - `handle` string required nullable
      - `name` string required
    - `registry_location` string nullable Deprecated: use `extras.tiktok.registry_location`. TikTok only.
    - `paid_by` string nullable Deprecated: use `extras.tiktok.paid_by`. TikTok only.
    - `running_ad_count` integer nullable Deprecated: use `ad_counts.running`. Meta, TikTok.
    - `total_ad_count` integer nullable Deprecated: use `ad_counts.total`. Meta, TikTok.
    - `ad_count_estimate` integer nullable Deprecated: use `ad_counts.estimate`. Google only.
- Option 2 object Returned instead of a Run when `estimate=true`. Nothing is charged; some operations add members.
  - `estimate_credits` integer required What the call would be charged, in Credits.
  - `cached` boolean required Whether a stored result can already answer. It does not change the price.

### 202 Accepted

Still running: `{ run }`. Poll `GET /v1/runs/{id}`.

object

Still running. Poll `poll_url` (`GET /v1/runs/{id}`), waiting the 202's `Retry-After` seconds between polls.

- `run` object required Every charged operation creates a Run; the envelope is the same inline or polled. Its fields are on [Poll or re-read a run](https://www.shortsintel.com/docs/reference/runs/get-run#response-200).
- `poll_url` string required format `uri` Absolute URL of `GET /v1/runs/{id}`, the body's copy of the `Location` header (for MCP). Present only while `running`.

202 · Example

```json
{
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "advertiser_lookup",
    "status": "running",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": null,
    "charge_credits": 0,
    "list_price_credits": 0,
    "cached": false
  },
  "poll_url": "https://www.shortsintel.com/v1/runs/run_8f2c1ad04b"
}
```

### 400 Bad Request

`invalid_request` (a malformed id, `wait`, `estimate` or Idempotency-Key) or `unsupported_platform`, refused before any Run opens. Nothing is charged.

Codes: `invalid_request`, `unsupported_platform`. The problem body and every code are on [Errors](https://www.shortsintel.com/docs/reference/errors).

### 401 Unauthorized

Codes: `missing_authorization`, `invalid_key`, `key_revoked`, `key_expired`, `invalid_token`. The problem body and every code are on [Errors](https://www.shortsintel.com/docs/reference/errors).

### 402 Payment Required

`insufficient_balance`: the Balance cannot cover the quoted price (the worst case for Research and enriched search). No Run opens and nothing is charged; a multi-item Run that runs short later charges its completed items up to the Balance and ends `partial`.

Code: `insufficient_balance`. The problem body and every code are on [Errors](https://www.shortsintel.com/docs/reference/errors).

### 409 Conflict

`idempotency_conflict` — the same Idempotency-Key with a different payload.

Code: `idempotency_conflict`. The problem body and every code are on [Errors](https://www.shortsintel.com/docs/reference/errors).

### 429 Too Many Requests

`rate_limit_exceeded` or `concurrency_limit_exceeded`, with `Retry-After`.

Codes: `rate_limit_exceeded`, `concurrency_limit_exceeded`. The problem body and every code are on [Errors](https://www.shortsintel.com/docs/reference/errors).

### 502 Bad Gateway

A Run that opened and then failed answers `application/problem+json` with its problem's status (`vendor_error` here, `not_found` as 404) and the Run envelope, keeping the Run id. Never charged. The example is a Video lookup's.

Code: `vendor_error`. The problem body and every code are on [Errors](https://www.shortsintel.com/docs/reference/errors).

### 503 Service Unavailable

`source_unavailable`: every source this Run reads failed or is switched off. The Run fails uncharged, envelope alongside; `endpoints` names the source. Retry after `retry_after_seconds` (also `Retry-After`); it does not mean empty. The example is a Video lookup's.

Code: `source_unavailable`. The problem body and every code are on [Errors](https://www.shortsintel.com/docs/reference/errors).

## Related guides

This call creates a Run. With `wait` it holds the response open until the Run finishes or the wait runs out, then answers with the finished result or `202` and the running Run. Poll [`GET /v1/runs/{id}`](https://www.shortsintel.com/docs/reference/runs/get-run) until it settles; re-reading a Run is free.

- [Runs](https://www.shortsintel.com/docs/concepts/runs): How a call becomes a Run, waiting inline, polling and free re-reads.
- [Pricing and estimates](https://www.shortsintel.com/docs/concepts/pricing-and-estimates): Credits, estimates and why a cached result costs the same as a fresh one.
- [Ads](https://www.shortsintel.com/docs/concepts/ads): Search Meta's, TikTok's and Google's ad libraries: the filters, what each Ad carries, the winner Score, Ad analysis, what is stored, and what a search costs.

## Request samples

curl:

```bash
curl "https://www.shortsintel.com/v1/advertisers/meta/100064000000001?wait=30" \
  -H "Authorization: Bearer sk_live_YOUR_KEY"
```

TypeScript:

```typescript
const response = await fetch(
  "https://www.shortsintel.com/v1/advertisers/meta/100064000000001?wait=30",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer sk_live_YOUR_KEY",
    },
  },
);

if (!response.ok) {
  throw new Error(`ShortsIntel ${response.status}`);
}

const data = await response.json();
```

Python:

```python
import requests

response = requests.get(
    "https://www.shortsintel.com/v1/advertisers/meta/100064000000001?wait=30",
    headers={
        "Authorization": "Bearer sk_live_YOUR_KEY",
    },
)
response.raise_for_status()

data = response.json()
```

200 · The Run finished inside the wait budget: `{ run, result }`. With `estimate=true`, `{ estimate_credits, cached }` instead.

```json
{
  "run": {
    "id": "run_8f2c1ad04b",
    "kind": "advertiser_lookup",
    "status": "completed",
    "created_at": "2026-09-08T09:14:02.418Z",
    "completed_at": "2026-09-08T09:14:04.930Z",
    "charge_credits": 15,
    "list_price_credits": 15,
    "cached": false
  },
  "result": {
    "page_id": "100064000000001",
    "name": "Plunge",
    "page_url": "https://www.facebook.com/plunge/",
    "instagram": {
      "handle": "plunge",
      "url": "https://www.instagram.com/plunge/"
    },
    "creator": {
      "id": "17841400000000001",
      "platform": "instagram",
      "handle": "plunge",
      "name": "Plunge"
    },
    "running_ad_count": 14,
    "total_ad_count": 61,
    "last_observed_at": "2026-10-12T08:00:00.000Z",
    "first_seen_at": "2026-09-02T10:15:00.000Z",
    "cached": false,
    "as_of": "2026-10-12T08:00:00.000Z",
    "library": "meta",
    "id": "100064000000001",
    "url": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=ALL&search_type=page&view_all_page_id=100064000000001",
    "ad_counts": {
      "running": 14,
      "total": 61,
      "estimate": null
    },
    "linked_accounts": [
      {
        "platform": "instagram",
        "handle": "plunge",
        "url": "https://www.instagram.com/plunge/",
        "display_name": null,
        "followers": null,
        "verified": null,
        "creator_id": "17841400000000001"
      }
    ],
    "domains": [],
    "extras": {
      "meta": {}
    }
  }
}
```

200 · With `estimate=true`: the price, no Run, no charge.

```json
{
  "estimate_credits": 15,
  "cached": false
}
```

[Previous Read a Google Ad's history](https://www.shortsintel.com/docs/reference/ads/list-google-ad-snapshots)[Next Look up an advertiser profile (old path)](https://www.shortsintel.com/docs/reference/ads/get-advertiser)
