# Library Tiktok — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search TikTok's Commercial Content Library to discover ads by company name or keyword, then view detailed information like creative format, scheduling dates, audience targeting, and video thumbnails. Monitor competitor advertising strategies and track ad campaigns across supported regions.

**Category:** Social Media | **Website:** [library.tiktok.com/ads?region=US&search_term=nike](https://library.tiktok.com/ads?region=US&search_term=nike) | **Docs:** [parse.bot/marketplace/ce77a253-8260-4d6c-8ae4-0627e508c5ed/library-tiktok-com-api](https://parse.bot/marketplace/ce77a253-8260-4d6c-8ae4-0627e508c5ed/library-tiktok-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-library-tiktok-com-api-ce77a253/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_ad_details

Get detailed information about a specific ad including advertiser info, targeting (location, age, gender), and creative assets. Returns targeting breakdown by region with audience size estimates.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ad_id` | string | Yes | The ad ID (from search_ads results, e.g. '1867460299162625') |
| `lang` | string | No | Language code for the response (e.g. 'en-US', 'fr-FR', 'de-DE') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-library-tiktok-com-api-ce77a253/get_ad_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ad_id":"<string>","lang":"<string>"}'
```

### get_supported_regions

Get the list of supported regions/countries available for filtering in the TikTok Ad Library. Returns European region codes and names that can be passed to search_ads as the region parameter.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `lang` | string | No | Language code for region name localization (e.g. 'en-US', 'fr-FR', 'de-DE') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-library-tiktok-com-api-ce77a253/get_supported_regions \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lang":"<string>"}'
```

### search_ads

Search the TikTok Ad Library for ads matching a query (advertiser name or keyword). Returns paginated results with ad metadata including creative format, dates, audience estimates, and media URLs. Paginates via offset+search_id; the search_id from the first response must be passed on subsequent pages.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `end_time` | integer | No | End of date range as Unix timestamp (seconds). Defaults to now. |
| `limit` | integer | No | Number of results per page (max 50) |
| `offset` | integer | No | Pagination offset (0-based). Requires search_id from a previous response for values > 0. |
| `query` | string | Yes | Search query (advertiser name or keyword) |
| `region` | string | No | Region/country code filter (e.g. 'FR', 'DE', 'GB') or 'all' for all regions. Use get_supported_regions for the full list of accepted codes. |
| `search_id` | string | No | Search ID returned from a previous search_ads call. Required when offset > 0 to paginate through results. |
| `sort_by` | string | No | Sort order: 'last_shown_date,desc' or 'last_shown_date,asc' |
| `start_time` | integer | No | Start of date range as Unix timestamp (seconds). Defaults to 1 year ago. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-library-tiktok-com-api-ce77a253/search_ads \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"end_time":"<integer>","limit":"<integer>","offset":"<integer>","query":"<string>","region":"<string>","search_id":"<string>","sort_by":"<string>","start_time":"<integer>"}'
```