# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/library-tiktok/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/library-tiktok/get-ad-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/library-tiktok/get-supported-regions \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/library-tiktok/search-ads \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.