# Upscrape Facebook Ad Library LLM Integration Prompt

Give this to an LLM or coding agent. It must fetch the OpenAPI spec first and use this brief only for orientation.

## First Step

Fetch and read this OpenAPI spec before writing code:

https://data.upscrape.com/catalog/platforms/fb-adlibrary/openapi.json?token=SFMyNTY.g2gDdAAAAAFtAAAAC3BsYXRmb3JtX2lkbQAAAAxmYi1hZGxpYnJhcnluBgB6aw1KnwFiAAFRgA.1uLiiQijNjtwRo5qS42snutUpbdl6YS2A7dWSklqZ90
This signed OpenAPI URL is valid for approximately 7 days.

## Hard Rules

- Use the OpenAPI spec as the source of truth for endpoints, request bodies, response bodies, errors, and JSON schemas.
- Do not infer fields from capability descriptions; fetch the spec and use its component schemas.
- Authenticate every request with `Authorization: Bearer YOUR_API_KEY`.
- Start runs with `POST /execute`; do not invent platform-specific execute endpoints.
- Poll `GET /jobs/{id}` or `GET /jobs/{id}/result` until `state` is `completed` or `failed`.
- Optionally send `Prefer: wait=N` on `POST /execute` to wait up to N seconds for inline results.
- If the response is `200`, the job completed — read `results[0].data`. If `202`, poll `GET /jobs/{id}`.
- `stream` is public-facing but must remain `false` today.

## API Base

- Base URL: `https://data.upscrape.com`
- OpenAPI spec: `https://data.upscrape.com/catalog/platforms/fb-adlibrary/openapi.json?token=SFMyNTY.g2gDdAAAAAFtAAAAC3BsYXRmb3JtX2lkbQAAAAxmYi1hZGxpYnJhcnluBgB6aw1KnwFiAAFRgA.1uLiiQijNjtwRo5qS42snutUpbdl6YS2A7dWSklqZ90`
- Execute endpoint: `POST /execute`
- Job poll endpoint: `GET /jobs/{id}`
- Result alias: `GET /jobs/{id}/result`
- Content-Type: `application/json`
- Optional header: `Idempotency-Key`
- Optional header: `Prefer: wait=N` (hold connection up to N seconds for synchronous result)

## Execution Flow

1. Send `POST /execute` with a platform capability ID and its `input` object.
2. The API responds with a queued `job_id`.
3. Poll the job endpoint until `state` becomes `completed` or `failed`.
4. If completed, read `results[0].data`; its exact shape is defined by the OpenAPI component schema for the selected capability.

## Example Execute Request

```json
{
  "capability": "fb-adlibrary.ad.search",
  "input": {
    "country": "US",
    "limit": 5,
    "query": "nike"
  }
}
```

## Optional Request Fields

- `network.session_id`: explicit reusable session identifier
- `network.session_key`: stable key used to derive a reusable session
- `network.sticky`: reuse the resolved session when `true`
- `timeout_ms`: per-capability timeout override up to the capability maximum listed below
- `stream`: must be `false`

## Supported Capabilities

- `fb-adlibrary.ad.search` - Search Ads. Searches the Facebook Ad Library by keyword. Returns raw ad data including creative content, targeting info, spend data, and all metadata. Supports filtering by language, platform, media type, active status, date range, and sorting. Max `timeout_ms`: 120000. Streaming: disabled.
- `fb-adlibrary.advertiser-ads.list` - List Advertiser Ads. Lists all ads from a specific Facebook advertiser by their page ID. Returns raw ad data with full filter support. Max `timeout_ms`: 120000. Streaming: disabled.