Guides
Best practices
Count before you pull
Counts are the cheapest call in the API. The same count is cached for five minutes, and each account can run 120 fresh scans a minute, up to 8 at a time. Size an audience with /count before you start an enrichment or an analysis that spends credits, and narrow it until the number is one your team can work.
Let AI draft the criteria, then review them
/ai-criteria turns a description of up to 2,000 characters into filters. Read what comes back, including unmatched, before you count: it is a draft, not a decision. It allows 20 requests a minute and 300 a day (50 a day without a subscription). Save the criteria that work in Audience Builder and read them back with the saved-criteria endpoints instead of drafting them again.
Check credits before you enrich
Enrichment spends credits per row: 200 a period on Starter, 500 on Growth. POST /api/v1/lead-generation/mcp/credits/preview with {"recordCount": 1200} tells you whether a list fits before you start, and a start that would overrun answers 402 with how many credits remain.
Poll long jobs slowly
Enrichment and AI analysis run as jobs. Start one, keep its id, and check status until it is completed or failed (analysis jobs can also be paused or cancelled). Every REST call with an API key counts toward the daily limit, status checks included, so check about once a minute. Over MCP, status checks are free. There are no webhooks: the web app's notification bell and emails tell people when a job finishes.
# Uses call() from the Errors guide (/docs/errors).
import time
job = call("POST", f"/api/v1/lead-generation/runs/{run_id}/enrich-jobs", {})
while job["status"] in ("pending", "running"):
time.sleep(60) # each status check with an API key counts toward the daily limit
job = call("GET", f"/api/v1/lead-generation/runs/{run_id}/enrich-jobs/{job['id']}")
if job["status"] == "failed":
raise RuntimeError(job["error"])
rows = call("GET", f"/api/v1/lead-generation/runs/{run_id}/results?mode=enrich")// Uses call() from the Errors guide (/docs/errors), in the same .mjs file.
let job = await call("POST", `/api/v1/lead-generation/runs/${runId}/enrich-jobs`, {});
while (job.status === "pending" || job.status === "running") {
// Each status check with an API key counts toward the daily limit.
await new Promise((resolve) => setTimeout(resolve, 60_000));
job = await call("GET", `/api/v1/lead-generation/runs/${runId}/enrich-jobs/${job.id}`);
}
if (job.status === "failed") throw new Error(job.error);
const rows = await call("GET", `/api/v1/lead-generation/runs/${runId}/results?mode=enrich`);Stay inside the rate limits
- One account can make 300 requests a minute and one IP address 120, on top of your plan's limits.
- Some route families have hourly budgets per account, such as 120 job starts, 60 uploads and 60 sends to tools an hour.
- Read
Retry-Afteron a 429 and wait that long. The Errors guide has a helper that does this. - Spread scheduled jobs across the day instead of starting them all at once.
Keep keys on the server
- Never ship an API key in browser or mobile code: anyone can read it there. Call GTM Scoop from your server and pass the result on.
- Send one credential per request:
Authorization: Bearerorx-api-key, never both. - Replace a key from your profile if it may have leaked. The old one stops working on its next call.