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

# How to Use TikTok Ad Library search in Instinct

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, with a Spiral API key |

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

- Every Monday, use TikTok Ad Library search to check Gymshark ads delivered in the UK over the past 14 days. Report ad IDs absent from the previous digest with their dates and public links.
- Each Friday, use TikTok Ad Library search to check IKEA ads delivered in Germany over the past 30 days. List newly observed ads and changes to their last shown dates.
- Every week, use TikTok Ad Library search to check Nike ads delivered in France over the past 14 days. Prepare a review list of newly observed ad links and available covers.
- On the first of each month, use TikTok Ad Library search to find Adidas ads delivered in Germany during the previous month. Report unique returned ad IDs and their audience ranges.
- Every Tuesday, use TikTok Ad Library search to check Duolingo ads delivered in the UK over the past 30 days. Compare the returned audience bands with the previous report and list changes.

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

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

### Use the Spiral skill

1. **Send Instinct 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 Spiral's MCP server

1. **Create an API key**: In the console, open API keys and create a key for Instinct. Copy it.

2. **Send Instinct this message**: Instinct reads Spiral's skill and asks for your API key.

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

3. **Give Instinct the key**: When Instinct asks for the key, add it where Instinct keeps secrets, never in the chat itself.

### 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: Instinct finds TikTok Ad Library search on Spiral, shows the price and runs it.

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

## 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 Instinct?

Produce a weekly digest of newly observed TikTok ads for a public brand. A scheduled agent can compare returned ad IDs and delivery dates with earlier searches to highlight changes for review.

### 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 Instinct guides](https://spiral.ai/integrations/instinct)

## 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)
- [Codex](https://spiral.ai/integrations/codex/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)
- [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 Instinct guides

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

## Questions about TikTok Ad Library search in Instinct

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

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

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

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 Instinct plan is separate.

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

You need no ScrapeCreators account. Instinct uses one Spiral API key for every tool, and Spiral runs TikTok Ad Library search on its own ScrapeCreators account.

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

About two minutes: create an API key, then send Instinct this message, then give Instinct the key.

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

TikTok Ad Library search runs in the background. Instinct 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.

