# Adspy API

Adspy API · https://www.adspy.sh/docs/api · Updated October 24, 2026

Adspy's library of public Meta and Google ads and brands' organic TikTok and YouTube posts, as a REST API for your own servers.

- Base URL: `https://www.adspy.sh/api/v1`
- Format: JSON, snake_case; errors as RFC 9457 problem details
- Authentication: Bearer API key, managed by your organization
- Description: OpenAPI 3.1 at https://www.adspy.sh/openapi.json
- Access: Adspy Enterprise; Instagram is not available in the API

## A first request

```sh
curl "https://www.adspy.sh/api/v1/brands?query=northstar&limit=5" \
  -H "Authorization: Bearer $ADSPY_API_KEY"
```

```js
const response = await fetch(
  "https://www.adspy.sh/api/v1/brands?query=northstar&limit=5",
  { headers: { Authorization: `Bearer ${process.env.ADSPY_API_KEY}` } },
);
const body = await response.json();
if (!response.ok) throw new Error(`${body.code}: ${body.detail}`);
for (const brand of body.data) console.log(brand.brand_key, brand.name);
```

```python
import os
import requests

response = requests.get(
    "https://www.adspy.sh/api/v1/brands",
    params={"query": "northstar", "limit": 5},
    headers={"Authorization": f"Bearer {os.environ['ADSPY_API_KEY']}"},
    timeout=70,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{body['code']}: {body['detail']}")
for brand in body["data"]:
    print(brand["brand_key"], brand["name"])
```

## What it covers

- Brands and creatives: Search brands and creatives, read a creative with its source ads, transcript and AI analysis, and find similar creatives of other brands.
- Reports: X-Ray, social report, Full Analysis and comparisons: evidence with its n and intervals, never spend or results.
- Social: TikTok and YouTube accounts and posts, with public counts, and posts run as ads.
- Collections, fetches and exports: Save creatives with notes, ask for brands and accounts Adspy does not have yet, and export up to 10,000 items.

## Guides

- [Quickstart](https://www.adspy.sh/docs/api/quickstart.md): From an API key to a brand's creatives and its Full Analysis in four requests.
- [Authentication and keys](https://www.adspy.sh/docs/api/authentication.md): One header, keys your organization manages, and permissions you can narrow.
- [Pagination](https://www.adspy.sh/docs/api/pagination.md): Lists page with an opaque cursor: send it back with the same filters.
- [Rate limits](https://www.adspy.sh/docs/api/rate-limits.md): Limits are set in your Enterprise contract and announced on every answer.
- [Idempotency](https://www.adspy.sh/docs/api/idempotency.md): One key per new request, the same key for its retries.
- [Jobs: fetches and exports](https://www.adspy.sh/docs/api/jobs.md): Collections and exports answer 202 with a job; read the job until it is done.
- [Media links](https://www.adspy.sh/docs/api/media-links.md): Media fields hold signed links: use them directly, refresh them by reading the record again.
- [Data model](https://www.adspy.sh/docs/api/data-model.md): Public evidence about brands' ads and organic posts, in stable snake_case fields.
- [Instagram is not available in the API](https://www.adspy.sh/docs/api/instagram.md): Instagram accounts and posts stay out of the API. Meta ads, including those on Instagram placements, stay in.
- [Changelog](https://www.adspy.sh/docs/api/changelog.md): What changed in the API, newest first.
- [Security](https://www.adspy.sh/docs/api/security.md): How keys and requests are protected, and how to reach us about a vulnerability.
- [Errors](https://www.adspy.sh/docs/api/errors.md): the problem format and every error code.
- [API reference](https://www.adspy.sh/docs/api/reference.md): every route, from https://www.adspy.sh/openapi.json.