[Integrations](https://spiral.ai/integrations) › [Codex](https://spiral.ai/integrations/codex) › [TikTok Ad Library search](https://spiral.ai/integrations/codex/tiktok-ad-library-search)

# How to Use TikTok Ad Library search in Codex

Search TikTok’s public Ad Library for advertiser names, ad links, available media, first and last shown dates, and estimated audience ranges. Use it to find campaign examples or compare a brand’s advertising activity over time.

|  |  |
| --- | --- |
| Model | TikTok Ad Library search |
| Available through | ScrapeCreators |
| Category | Social Media |
| Price | Up to $0.0013 per run. |
| Returns | json |
| Runs | In the background |
| Setup | About 2 minutes, no API key |

## Prompts to try with TikTok Ad Library search in Codex

- Use TikTok Ad Library search to find Gymshark ads last shown in the UK during October 2026, then create a CSV in this project with ad IDs, advertiser names, dates, audience ranges, and public links.
- Use TikTok Ad Library search to find IKEA ads delivered in Germany during October 2026 and build a campaign timeline in this project from the returned first and last shown dates.
- Use TikTok Ad Library search for Nike ads delivered in France during October 2026 and add a review page to this project showing the returned ad links and available covers.
- Use TikTok Ad Library search to find Adidas ads delivered in Germany during September and October 2026, then compare unique returned ad IDs by month in a project report.
- Use TikTok Ad Library search to find Duolingo ads delivered in the UK during October 2026 and create a deduplicated JSON dataset in this project with delivery dates and audience ranges.

## How to set up TikTok Ad Library search in Codex

Pick the way that suits you. Each takes about two minutes.

### Use Spiral's MCP server

1. **Add the hosted server**

```bash
codex mcp add spiral --url https://api.spiral.ai/mcp
```

2. **Sign in**: Codex opens the browser: sign in to Spiral and click Authorize. No API key. `codex mcp list` then shows Spiral.

```bash
codex mcp login spiral
```

### Use the Spiral skill

1. **Send Codex this message**: Your agent reads Spiral's skill and sets itself up.

```
set up https://spiral.ai/SKILL.md
```

2. **Sign in or paste a key**: Approve Spiral in the browser, or give the agent a key from the console.

### Use the Spiral CLI

1. **Install and sign in**: Installs the Spiral CLI, signs you in and adds its skill to your coding agents.

```bash
npx -y spiral-cli@latest init
```

### Call the Spiral API

1. **Create an API key**: In the console, under API keys.

2. **Run TikTok Ad Library search**: One request; the result comes back by polling or a webhook.

```bash
curl https://api.spiral.ai/v1/runs \
  -H "Authorization: Bearer $SPIRAL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "provider": "scrapecreators",
    "model": "scrapecreators/tiktok-ad-library-search",
    "input": {
      "query": "The Creator Loop"
    }
  }'
```

Then paste one of the prompts above: Codex finds TikTok Ad Library search on Spiral, shows the price and runs it.

Setup guide in the docs: https://spiral.ai/docs/quickstarts/codex

## TikTok Ad Library search tools and prices

- [TikTok Ad Library · Ad Library Search](https://spiral.ai/tools/scrapecreators/scrapecreators/tiktok-ad-library-search) (ScrapeCreators): Up to $0.0013 per run.

## Settings you can ask for

| Setting | Allowed values | Default | Description |
| --- | --- | --- | --- |
| query |  | — | General ad search. Provide either query or advertiser_name, not both. |
| cursor |  | — | Opaque cursor returned from the previous response. Repeat the same query or advertiser_name, adv_biz_ids when used, and any explicit start_time, end_time and region filters with every returned cursor. Pass the cursor unchanged; it does not replace the search inputs or filters. |
| region | all, AT, BE, BG, BR, CH, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IS, IT, LI, LT, LU, LV, MT, NL, NO, PL, PT, RO, SE, SI, SK, TR | all | Filter by the ad's targeting/delivery country, not the advertiser's registration country. Omitted region defaults to all supported countries, not every country worldwide. Values are case-insensitive; choose all or one of the listed country codes. US is not supported. Empty values, unsupported countries and multiple countries return 400 bad_request. |
| end_time |  | — | Inclusive upper bound for the ad's last shown date; start_time is the inclusive lower bound. Supply start_time and end_time together as positive base-10 safe integers, no greater than 9007199254740991, in Unix seconds (preferred) or milliseconds. Values greater than 9999999999 are interpreted as milliseconds, divided by 1000 and rounded down to seconds. start_time must be less than or equal to end_time after normalization; equal bounds are accepted. If both are omitted, the last-shown date window defaults to the rolling 30 days ending at the time of each request. A missing companion, empty value, sign, fraction, scientific notation, whitespace, date string, unsafe integer or reversed interval returns 400 bad_request. |
| start_time |  | — | Inclusive lower bound for the ad's last shown date; end_time is the inclusive upper bound. Supply start_time and end_time together as positive base-10 safe integers, no greater than 9007199254740991, in Unix seconds (preferred) or milliseconds. Values greater than 9999999999 are interpreted as milliseconds, divided by 1000 and rounded down to seconds. start_time must be less than or equal to end_time after normalization; equal bounds are accepted. If both are omitted, the last-shown date window defaults to the rolling 30 days ending at the time of each request. A missing companion, empty value, sign, fraction, scientific notation, whitespace, date string, unsafe integer or reversed interval returns 400 bad_request. |
| adv_biz_ids |  | — | TikTok advertiser business ID from a See all ads link. Use it with advertiser_name to pin the exact advertiser. Required companion: advertiser_name; ID-only searches return 400 because TikTok ignores the ID without the name. |

## What can you do with TikTok Ad Library search in Codex?

Build a competitor ad timeline from TikTok ad IDs, delivery dates, and public links. A coding agent can turn the returned records into a deduplicated table or campaign review page in your project.

### Competitor campaign timelines

Arrange a public brand’s returned ads by first and last shown dates to build a campaign timeline with links to the original records.

### Creative review shortlists

Collect ad detail links and available video previews for a creative team’s review before planning a new campaign.

### Weekly brand advertising reports

Compare successive searches for a brand and report newly observed ad IDs with their first shown dates.

### Seasonal campaign research

Find a retailer’s ads around Black Friday or a summer promotion and compare the returned delivery dates.

### Audience range comparisons

Compare the estimated audience bands attached to returned ads and prepare a review list without converting bands into exact counts.

### Country-specific campaign reviews

Run separate searches for a brand’s ads delivered in Germany and France, then compare the returned ad IDs and dates.

### Agency research handoffs

Prepare a deduplicated table of advertiser names, ad IDs, dates, audience ranges, and public links for an account team.

## Overview

- [ScrapeCreators](https://spiral.ai/providers/scrapecreators)
- [All Codex guides](https://spiral.ai/integrations/codex)

## TikTok Ad Library search in other agents

- [Amp](https://spiral.ai/integrations/amp/tiktok-ad-library-search)
- [ChatGPT](https://spiral.ai/integrations/chatgpt/tiktok-ad-library-search)
- [Claude](https://spiral.ai/integrations/claude-desktop/tiktok-ad-library-search)
- [Claude Code](https://spiral.ai/integrations/claude-code/tiktok-ad-library-search)
- [Cline](https://spiral.ai/integrations/cline/tiktok-ad-library-search)
- [Cursor](https://spiral.ai/integrations/cursor/tiktok-ad-library-search)
- [Devin](https://spiral.ai/integrations/devin/tiktok-ad-library-search)
- [dots](https://spiral.ai/integrations/dots/tiktok-ad-library-search)
- [Factory Droid](https://spiral.ai/integrations/factory-droid/tiktok-ad-library-search)
- [Gemini](https://spiral.ai/integrations/gemini/tiktok-ad-library-search)
- [Gemini CLI](https://spiral.ai/integrations/gemini-cli/tiktok-ad-library-search)
- [Google Antigravity](https://spiral.ai/integrations/antigravity/tiktok-ad-library-search)
- [goose](https://spiral.ai/integrations/goose/tiktok-ad-library-search)
- [Grok](https://spiral.ai/integrations/grok/tiktok-ad-library-search)
- [Grok Build](https://spiral.ai/integrations/grok-build/tiktok-ad-library-search)
- [Hermes](https://spiral.ai/integrations/hermes/tiktok-ad-library-search)
- [Instinct](https://spiral.ai/integrations/instinct/tiktok-ad-library-search)
- [Manus](https://spiral.ai/integrations/manus/tiktok-ad-library-search)
- [Muse](https://spiral.ai/integrations/muse/tiktok-ad-library-search)
- [Muse Code](https://spiral.ai/integrations/muse-code/tiktok-ad-library-search)
- [n8n](https://spiral.ai/integrations/n8n/tiktok-ad-library-search)
- [Notion](https://spiral.ai/integrations/notion/tiktok-ad-library-search)
- [OpenClaw](https://spiral.ai/integrations/openclaw/tiktok-ad-library-search)
- [opencode](https://spiral.ai/integrations/opencode/tiktok-ad-library-search)
- [Perplexity](https://spiral.ai/integrations/perplexity/tiktok-ad-library-search)
- [Raycast](https://spiral.ai/integrations/raycast/tiktok-ad-library-search)
- [VS Code](https://spiral.ai/integrations/vscode/tiktok-ad-library-search)
- [Windsurf](https://spiral.ai/integrations/windsurf/tiktok-ad-library-search)
- [Zapier](https://spiral.ai/integrations/zapier/tiktok-ad-library-search)

## More Codex guides

- [TikTok Ad Library Ad Library Ad](https://spiral.ai/integrations/codex/tiktok-ad-library-ad-library-ad)
- [TikTok App Check if live room is online](https://spiral.ai/integrations/codex/tiktok-app-check-if-live-room-is-online)
- [Threads user posts](https://spiral.ai/integrations/codex/threads-user-posts)
- [TikTok App Get comment replies data of specified video](https://spiral.ai/integrations/codex/tiktok-app-get-comment-replies-data-of-specified-video)
- [Threads top post search](https://spiral.ai/integrations/codex/threads-top-post-search)
- [TikTok App Get details of specified hashtag](https://spiral.ai/integrations/codex/tiktok-app-get-details-of-specified-hashtag)

## Questions about TikTok Ad Library search in Codex

**Can Codex use TikTok Ad Library search?**

Yes. Add Spiral to Codex as an MCP server, and Codex can find and run TikTok Ad Library search like any built-in tool.

**How much does TikTok Ad Library search cost in Codex?**

Up to $0.0013 per run. You pay from your Spiral balance as you go, with no subscription, and a failed run is not charged. Your Codex plan is separate.

**Do I need a ScrapeCreators account to use TikTok Ad Library search in Codex?**

No. Spiral runs TikTok Ad Library search on its own ScrapeCreators account. You sign in to Spiral once and never paste a key.

**How long does it take to set up TikTok Ad Library search in Codex?**

About two minutes: add the hosted server, then sign in.

**Does Codex wait while TikTok Ad Library search runs?**

TikTok Ad Library search runs in the background. Codex starts the run, checks on it and gives you the json when it's ready.

**Does TikTok’s Ad Library cover advertising worldwide?**

TikTok’s published coverage includes ads targeted to the EEA, Switzerland, and the UK. These results should not be treated as a worldwide inventory.

**How quickly do new ads appear?**

TikTok says ads generally enter the library within 24 hours of campaign initiation.

**How far back does the advertising history go?**

TikTok retains advertisement data while an ad runs and until one year after it was last shown.

**Are the audience figures exact?**

TikTok reports unique users seen as estimated ranges. Keep those ranges intact when comparing ads.

**Will a search return every matching ad?**

ScrapeCreators explicitly warns that results may be incomplete or duplicated. It recommends narrower date windows to reduce pagination.

