Custom GPT Actions API for Ad Research: Wiring ChatGPT to Live Ads

Ask plain ChatGPT what video ads Gymshark is running in Germany right now and you get a confident guess stitched together from training data that went stale months ago. Route the same question through a custom GPT Actions API connection and you get a real answer: live creatives, runtimes, country flags, and estimated spend, fetched the second you hit enter.

TL;DR: A custom GPT plus one OpenAPI schema turns competitor ad research into a conversation. This guide gives you the exact custom GPT Actions API schema for the AdLibrary search endpoint, the bearer auth setup in the GPT Builder, credit-aware instructions that keep your GPT from burning budget on runaway queries, and the honest limits: no inline images, capped response sizes, 10 requests per minute. Build time is roughly 20 minutes on a ChatGPT Plus or Team plan with an AdLibrary Business key.

That conversion, from "open four ad libraries and start screenshotting" to "ask the question in chat," is what this post builds. The rest is the wiring diagram.

What a Custom GPT With Actions Actually Does

A custom GPT is a configured instance of ChatGPT: your instructions, your knowledge files, and the part that matters here, your Actions. Actions, documented in OpenAI's GPT Actions guide, let the model call external HTTP APIs in the middle of a conversation. You describe the API in an OpenAPI schema. The model reads that schema, decides when a user request needs live data, fills in the parameters itself, fires the request, and folds the JSON response into its answer.

No code runs on your side. The schema is the integration. That is what makes the custom GPT Actions API route the lowest-effort option in OpenAI's stack: no function-calling code, no webhook relay, no hosting bill, and nothing to redeploy when you tweak a parameter description.

For ad research, the bottleneck was never the chat layer. It was the data source. Every platform ships its own transparency tool (Meta's Ad Library, Google's Ads Transparency Center, LinkedIn's Ad Library), and tab-hopping between them is exactly the chore a chat interface should kill.

Meta's free Ad Library API looks like the obvious data source and turns out to be the wrong one for this job. It was built for political-ad transparency, so it returns political and social-issue ads worldwide but full commercial coverage only for the EU and UK. Add app review, identity verification, and access tokens that expire every 60 days, and it is a rough fit for a chatbot that needs to answer "what is Nike running on TikTok" on a Tuesday afternoon. We unpacked the full gap list in Meta's Ad Library API limitations.

The AdLibrary API is the paid power-user route built for this exact use: one bearer key, eleven platforms (Facebook, Instagram, TikTok, YouTube, Google, LinkedIn, Twitter, Pinterest, Yahoo, Unity Ads, AdMob), and performance signals on every commercial ad: estimated spend, a 0-1000 heat score, impressions, and runtime. Meta's API stays the right choice if political ads on Meta are genuinely all you need; the comparison in free vs paid ad library APIs draws that line precisely. New to the category? Start with what an ad library API actually is, then come back.

Prerequisites: One Plan, One Key, One Schema

You need three things before the GPT Builder is worth opening.

A ChatGPT plan that can build GPTs. Creating custom GPTs with Actions requires Plus, Team, or Enterprise. The Team plan is where this setup pays off hardest: one marketer wires it, twelve teammates query it, nobody else ever touches a schema.

An AdLibrary API key. API access lives on the Business plan (€329/mo, 1000+ credits per month). Generate a key from your dashboard. It starts with adl_, it is shown exactly once, and you can hold up to 10 keys per account, which makes per-client or per-environment separation painless. Details live on the API access feature page. No app review, no OAuth flow, no token refresh job to babysit.

Twenty minutes. The schema below is paste-ready.

The credit math is simple enough to design around. A search costs 1 credit. An AI creative analysis costs 1 credit. The cross-platform brand lookup is free, and a failed search refunds its credit automatically. A 1,000-credit month supports a daily research-chat habit comfortably, but only if your GPT's instructions respect the meter. That gets its own section.

The Worked Example: A Custom GPT Actions API Schema for Ad Search

In the GPT Builder, open Configure → Create new action and paste a schema. Here is a working one for the AdLibrary /api/search endpoint, written against OpenAPI 3.1:

openapi: 3.1.0
info:
  title: AdLibrary Ad Search
  description: Live commercial ads across Facebook, Instagram, TikTok,
    YouTube, Google, LinkedIn, Twitter, Pinterest, and more.
  version: 1.0.0
servers:
  - url: https://adlibrary.com
paths:
  /api/search:
    post:
      operationId: searchAds
      summary: Search live ads by keyword, platform, country, format,
        and recency. Costs 1 credit per call, including each extra page.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [appType]
              properties:
                keyword:
                  type: string
                  description: Brand, product, or ad-copy term,
                    e.g. "Gymshark" or "protein powder".
                appType:
                  type: string
                  enum: ["3"]
                  description: Vertical. Always send "3" (e-commerce).
                platform:
                  type: array
                  items:
                    type: string
                    enum: [facebook, instagram, tiktok, youtube,
                      google, linkedin, twitter, pinterest]
                  description: Platforms to search. Omit for all.
                geo:
                  type: array
                  items:
                    type: string
                  description: Country codes, e.g. ["DEU"] for Germany,
                    ["USA"] for the United States.
                adsType:
                  type: array
                  items:
                    type: string
                    enum: ["1", "2", "3", "4"]
                  description: Creative format. 1 = image, 2 = video,
                    3 = carousel, 4 = collection.
                daysBack:
                  type: number
                  enum: [1, 3, 7, 14, 30, 60, 90, 180, 365]
                  description: Only ads seen within this many days.
                sortField:
                  type: string
                  enum: ["-impression", "-heat_degree", "-days",
                    "-first_seen", "-last_seen", "-correlation"]
                  description: Sort order. "-days" = longest-running
                    first (proven ads), "-heat_degree" = trending,
                    "-impression" = biggest reach.
                page:
                  type: number
                  description: Page number, starts at 1.
                    Every page costs 1 credit.
                pageSize:
                  type: number
                  description: Results per page. Keep at 10 or
                    below for chat use.
      responses:
        "200":
          description: Matching ads with copy, engagement, impressions,
            estimated spend, heat score, runtime, geo, and landing page,
            plus a total match count and remaining credit balance.

A few choices in that schema are load-bearing, because in Actions the schema doubles as prompt engineering:

• operationId: searchAds is the tool name the model reasons with. Keep it verb-first and literal.
• Descriptions are instructions. "Costs 1 credit per call" inside the summary means the model carries the price into its planning. The sortField description teaches it that runtime signals a proven ad, so when you ask for winners it sorts by -days without being told.
• appType is pinned to "3". A single-value enum stops the model from improvising verticals; commercial ad research lives in e-commerce.
• pageSize guidance keeps responses chat-sized. The limits section explains why that matters more than you would expect.

Save the action and the GPT Builder validates the schema on the spot; a parse error surfaces inline before you ever run a test call.

Configuring Bearer Authentication in the GPT Builder

Below the schema editor sits the Authentication panel. Set it to API Key, pick Bearer as the auth type, and paste your adl_ key. ChatGPT stores the key encrypted and attaches Authorization: Bearer adl_... to every action call. The key never appears in the schema, the conversation, or anything a user of your GPT can see.

Two operational notes that save real pain:

1. Sharing scope is spending scope. Anyone who can use your GPT spends your credits through your key. Keep it on "Only me" while you test, then workspace-only on a Team plan once it behaves. Publishing this GPT to the public store would hand strangers your credit balance.
2. Rotate by key, not by GPT. AdLibrary allows up to 10 keys, so give this GPT its own dedicated one. When a key leaks or a teammate leaves, you revoke one key and rebuild nothing.

That is the entire integration: no server and no middleware. The first time the GPT fires the action, ChatGPT asks for a one-click confirmation, and then you are live.

Instructions That Respect Your Credit Balance

The schema defines what the GPT can do. Instructions define what it should do, and with a metered API the difference is money. Paste something like this into the Instructions field:

You are an ad research analyst with live access to the AdLibrary API.

CREDIT RULES
- searchAds costs 1 credit per call. Every page is a new credit.
- Never run more than one paid search per user message unless the
  user explicitly approves more.
- Never paginate on your own. Ask: "Want page 2? It costs 1 credit."
- After every paid call, report the balance from _credits.remaining.
- On a 402 error, stop and tell the user to add credits. Never retry.

RESEARCH DEFAULTS
- Always send appType "3".
- Default to daysBack 30 and pageSize 10 unless asked otherwise.
- "Winning" or "proven" ads: sortField "-days". "Trending right now":
  "-heat_degree". "Biggest reach": "-impression".
- Germany is geo ["DEU"], the US ["USA"], the UK ["GBR"].

REPORTING RULES
- Spend figures are estimates. Always say "estimated spend".
- Summarize patterns first (hooks, formats, offers), then list the
  top 3-5 ads with advertiser, runtime in days, format, and
  landing page URL.
- If the user asks how big a market is, run one search and quote
  the "total" field instead of fetching more pages.

Every block earns its place. The credit rules exist because an eager model will happily fan out five searches to be thorough, which is five credits spent answering one vague question. The reporting rules exist because the API returns estimated spend and reach signals, and your GPT should never dress estimates up as accounting data. The total rule covers market sizing: the search response includes a total match count, so "how many collagen ads ran this month" is a one-credit answer rather than a twenty-page crawl.

This split, capabilities in the schema and economics in the instructions, is the same pattern that makes any AI agent safe to hand a budget: a tool, plus a policy for the tool.

Add the Free Brand Lookup as a Second Action

One more path makes the GPT noticeably sharper on brand questions. The /api/advertisers/search endpoint resolves a brand name across Meta, Google, and LinkedIn in one call, reports when the platforms agree it is the same advertiser, and costs nothing. Append it to the same schema:

  /api/advertisers/search:
    get:
      operationId: findAdvertiser
      summary: Resolve a brand name to its advertiser accounts across
        Meta, Google, and LinkedIn. Free, 0 credits. Call this before
        searchAds whenever the user names a brand.
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Brand name, e.g. "Gymshark".
        - name: country
          in: query
          schema:
            type: string
          description: Two-letter country code, default US.
      responses:
        "200":
          description: Best-match advertiser with per-platform
            candidates and ad counts.

The phrase "call this before searchAds whenever the user names a brand" does real work. The model sequences the free probe ahead of the paid call on its own. The lookup also defuses the multi-account trap: big brands run several advertiser accounts (a flagship page, regional pages, sub-brands), so the GPT confirms which entity it is researching before spending anything. Free probe first, paid call second is the core discipline of every solid integration on this API, and it transfers unchanged from Python scripts to chat.

Example Research Conversations

Here is what the finished GPT feels like in practice. Three patterns cover most real usage: the competitor check, the market read, and the follow-up.

The competitor check.

You: What video ads is Gymshark running in Germany right now?

GPT: (calls findAdvertiser, free, confirms the right Gymshark account, then searchAds with keyword "Gymshark", adsType ["2"], geo ["DEU"], daysBack 30) Gymshark has active video ads in Germany this month. The dominant pattern: athlete-led hooks in the first two seconds, 9:16 vertical cuts, and a recurring leggings offer. The longest-running video has been live 47 days, a strong signal it converts. Top three by runtime: ... Balance: 982 credits.

The market read.

You: How crowded is "collagen supplement" advertising in the US?

GPT: (one searchAds call, quotes the total field) The search reports several thousand matching ads seen in the last 30 days. Sorting by heat, the top advertisers right now are... One credit spent, 981 remaining.

Notice the GPT never paginated and never re-searched. The instructions block did that, not luck.

The follow-up that justifies the build.

You: Take the longest-running ad from that list. What's the hook, and what would I brief differently?

GPT: (no new call, reasons over data already in context) The hook is a problem-question overlay in the first frame, followed by a before-after cut. A different angle worth testing against it: ...

That third exchange is the argument for the whole setup. A dashboard answers the query; the conversation answers the next question for free, because the JSON is already in context. The model compares hooks and offers in plain language, the way you would want raw creative research summarized before a briefing.

When you want full teardowns (scene-by-scene transcripts, persuasion analysis, a 1:1 replication brief) the API's enrichment endpoint handles that as a third action for 1 credit per ad. We covered it end to end in the AI ad creative analysis API guide, and the AI Ad Enrichment feature page shows what comes back.

The Limits: Inline Images, Context, and Rate Caps

A custom GPT for ad research is genuinely useful and clearly bounded. Every custom GPT Actions API integration inherits the same platform ceilings, and ad data reaches them sooner than most payloads do. Know the edges before you demo it to your team.

No inline ad creatives. ChatGPT does not render images returned by an action inside the chat. Your GPT can hand you preview_img_url links to open and it reasons well about copy, runtime, and engagement, but visual browsing stays on a dashboard. If your workflow is "show me 50 thumbnails and let my eyes do the filtering," chat is the wrong surface.

Response size and time are capped. OpenAI's production notes for Actions document hard ceilings on action calls, including a 100,000-character response limit and a 45-second timeout. Ad objects are heavy: copy, URLs, engagement, geo. A 60-result page can blow past what the model ingests cleanly, which is exactly why the schema pins pageSize at 10. Small pages, more turns.

Context fills up. Every search response lands in the conversation context. Ten searches into one session, early results fade from working memory and answers drift vague. Long research projects work better as several short conversations than one marathon thread.

Rate limits are real. The API allows 10 requests per minute and 10,000 per day per key. A chat GPT will never graze the daily cap, but a user spamming follow-ups can hit the per-minute one and draw a 429 with a Retry-After header. The one-search-per-message instruction keeps you clear of it.

None of these are blockers. They are design constraints, and the schema and instructions above already encode the workarounds.

When a Custom GPT Beats a Dashboard

The honest scorecard.

The GPT wins when:

• Questions are conversational. "What changed in Alo Yoga's ads since last month?" has no dashboard filter equivalent.
• The asker is non-technical. Account managers and creative leads get competitive intelligence without learning a single filter.
• Synthesis matters more than browsing. Compare hooks and cluster angles, or turn findings straight into a brief.
• Research is ad hoc. A few sharp questions a day, each answered in seconds.

The dashboard wins when:

• You need to see creatives. Thumbnails, video playback, side-by-side visual scanning.
• Volume is the job. Reviewing 200 ads to build a swipe file is a scrolling task, not a chat.
• You want precise filter stacking. Aspect ratio plus engagement floor plus e-commerce platform is faster clicked than typed.

Neither wins when the job is scheduled monitoring. "Tell me when a competitor launches a new concept" is not a chat; it is a cron job. That is automated competitor ad monitoring territory, with ready-made recipes for n8n and Zapier, and the automate competitor ad monitoring use case maps the full architecture.

When findings need to feed budget decisions, push them into numbers: the ad spend estimator for sizing a rival's outlay from the estimated-spend signals, and the ROAS calculator for modeling what matching that spend would need to return.

Custom GPT Actions API vs Claude MCP: Two Routes, One Dataset

Custom GPT Actions are OpenAI's answer to the question Anthropic answers with MCP servers: how does a chat model get live ad data?

If your company lives in ChatGPT, build the GPT. If it lives in Claude, build the server: the build-your-own AdLibrary MCP server guide is the direct counterpart to this post, the Meta ads MCP setup guide covers the campaign-management side, and Claude Code AdLibrary API workflows goes past chat into scripted research runs. Prompt patterns transfer almost one-to-one between ecosystems, as the MCP prompts library shows, and if you are still picking a camp, ChatGPT vs Claude vs Gemini for marketing compares them on real tasks.

Either way, the data layer is identical: one key, eleven networks via multi-platform coverage, the same credits. The ad data for AI agents use case describes the pattern both clients implement, so nothing stops you running both against one Business subscription.

Frequently Asked Questions

Do I need a paid ChatGPT plan to build a custom GPT with Actions?

Yes. Building custom GPTs with Actions requires ChatGPT Plus, Team, or Enterprise. On Team and Enterprise you can share the finished GPT across your workspace, so one person maintains the schema and the whole marketing team queries live ad data by chat.

How much does the AdLibrary API cost for a custom GPT setup?

API access is part of the AdLibrary Business plan at €329/mo, which includes 1000+ monthly credits. A search costs 1 credit, the brand lookup is free, and failed searches refund automatically, so a 20-30 search daily research habit fits comfortably inside the allowance.

Can my custom GPT show ad images inside the chat?

No. ChatGPT does not render images returned by Actions inline. Your GPT returns preview and landing-page URLs you can open in a browser, and it analyzes ad copy, runtime, and engagement signals directly in the chat. For visual browsing of creatives, use the AdLibrary dashboard alongside the GPT.

Why does my custom GPT action return a 401 or 429 error?

A 401 means the bearer key is missing or invalid: re-paste the full adl_ key in the action's authentication panel and confirm the auth type is set to Bearer. A 429 means you hit the 10-requests-per-minute rate limit; the response carries a Retry-After header, and spacing out queries resolves it.

Is this the same as Meta's free Ad Library API?

No. Meta's free API is built for political-ad transparency: it covers political and social-issue ads, with commercial ads only for the EU and UK, on Meta platforms alone, after app review. The AdLibrary API is a paid alternative covering commercial ads across eleven platforms, with spend estimates, heat scores, and runtime on every ad.

Wire It Up Before the Next Launch

A custom GPT Actions API build is that rare automation project with a 20-minute payoff. One schema, one bearer key, an instructions block, and competitor research becomes a question you ask instead of a chore you schedule. The Gymshark-in-Germany query that opened this post is now a one-credit call, and the follow-ups about hooks and angles cost nothing because the data already sits in the conversation.

Build order, one last time: get an API key on the Business plan at €329/mo with 1000+ credits and full API access, paste the search schema, set bearer auth, add the credit rules, then append the free brand lookup. Test against one brand you know well, sanity-check the output against the dashboard, and share it with your workspace. The custom GPT Actions API route covers the conversational half of your research; pair it with scheduled monitoring for the always-on half, and the next time someone asks what a competitor is running, the answer takes one message.