Skip to main content

DocsREST API and MCP server

API best practices

Endpoints, auth and live samples for Audience Builder, Connect Data and CRM sync.

Base URLhttps://us-farmvision-new-api.onrender.com

Guides

Best practices

Patterns that keep integrations fast, cheap and predictable.

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.

Python · poll an enrichment
# 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")
Node.js · poll an enrichment
// 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-After on 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: Bearer or x-api-key, never both.
  • Replace a key from your profile if it may have leaked. The old one stops working on its next call.

Related

Cookies on GTM Scoop

Essential cookies keep you signed in and the site secure, and are always on. Optional cookies (Google Analytics) help us understand how the site is used. They are on by default, except in the EU/EEA, the UK and Switzerland, where they stay off until you choose Accept All Cookies; choose Essential Cookies Only to turn them off. We do not use advertising cookies and we do not sell or share your personal information. The site works the same whichever you choose. We keep a record of your choice with the date, your IP address and the page you were on. Cookie Policy · Privacy Policy