REST API

You want to pull your AI Peekaboo data programmatically, whether that's for a custom dashboard, an automation, or feeding another tool.

Base URL and authentication

The API base URL is:

https://www.aipeekaboo.com/api/v1

Authenticate every request with an X-API-Key header (a lowercase x-api-key or an Authorization: Bearer header work too). Your key looks like:

pk_{projectId}_{secret}

Generate a key from Settings → Integrations. You can revoke a key at any time from the same page.

Read vs. read+write scopes

When you generate a key, you choose its scope:

• Read keys can pull data: brands, visibility, competitors, sources, prompts, categories, recommended prompts, and eligible local tracking data.
• Read+write keys can also create, update, and delete brands, prompts, competitors, and categories, and configure or pause eligible local tracking.

The read endpoints you'll use most

These GET endpoints cover the same core data you see in the dashboard. Any valid key can call them.

A worked example: the snapshot call

One authenticated GET gives you the whole picture for a brand:

curl -H "X-API-Key: $API_KEY" \
  https://www.aipeekaboo.com/api/v1/brands/$BRAND_ID/snapshot

The response wraps everything in the standard envelope, with the payload under data:

{
  "success": true,
  "data": {
    "brand": { "id": "a1b2c3d4-...", "name": "Acme Corp" },
    "snapshotDate": "2026-02-24T02:00:00.000Z",
    "visibility": {
      "score": 42,
      "rank": 3,
      "maxScore": 100,
      "totalCitations": 87,
      "totalChatsAnalyzed": 40
    },
    "prompts": [
      {
        "promptText": "Best project management tools for teams",
        "category": "Discovery",
        "mentions": 8,
        "averageScore": 78,
        "aiModels": ["gpt-4o-mini", "gemini-2.5-flash", "sonar"]
      }
    ],
    "sources": [
      { "domain": "forbes.com", "mentions": 12, "aiModels": ["gpt-4o-mini"] }
    ],
    "competitors": [
      {
        "id": "c1d2e3f4-...",
        "name": "Competitor A",
        "url": "https://competitor-a.com",
        "score": 58,
        "change": "+12%",
        "monthlyVisits": 4500000,
        "globalRank": 12000,
        "rank": 1
      }
    ],
    "aiSuggestions": ["Focus on discovery prompts where competitors outrank you"],
    "traffic": {
      "monthlyVisits": 250000,
      "globalRank": 45000,
      "countryRank": 8500,
      "bounceRate": 0.42,
      "pagesPerVisit": 3.2,
      "avgTimeOnSite": 185
    },
    "window": "latest_run"
  },
  "metadata": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-02-25T14:30:00.000Z",
    "queryTimeMs": 10
  }
}

Every response uses that same envelope: success, then data, then metadata carrying a requestId worth quoting in any support ticket. Paginated endpoints add a pagination object with offset, limit, total, and hasMore. If analysis hasn't run for the brand yet, snapshot comes back null rather than erroring.

Charting your daily trend

/visibility/timeseries returns one score per UTC day for your brand plus every tracked competitor, which is what you want if you're building your own chart rather than reading the single headline number from /visibility:

curl -H "X-API-Key: $API_KEY" \
  "https://www.aipeekaboo.com/api/v1/brands/$BRAND_ID/visibility/timeseries?time_range=30d"

Each point is that day's run-weighted mean over a whole UTC day. Days can carry unequal run counts, so averaging the daily points yourself will NOT equal the /visibility headline: the headline uses a rolling window and a different aggregation (a pooled mean across every run in the window, not a mean of daily means). The series array has days + 1 entries, inclusive of both the start and end of the requested window (a time_range=30d request returns 31 points, one per day plus today).

Two null-handling rules matter here, and both trace back to the same principle as the dashboard: never draw an unmeasured day as a 0.

• `score: null` means unmeasured, not zero. A day with no analysis runs at all renders null on every entity's series for that day. A real 0 means a run happened and the entity genuinely wasn't mentioned; those are different facts, and averaging them together would understate everyone's score.
• Every tracked competitor appears, even ones with `measured: false`. A competitor that was never mentioned anywhere in the window still shows up in the competitors array (so you don't have to guess whether it's tracked), with measured: false. That flag is informational only, not a rule about the scores themselves: an unmeasured competitor still gets a real 0 on any day your brand ran and was simply not mentioned, and null only on a day your brand itself has no runs - the identical rule above, applied per competitor. A soft-deleted competitor, by contrast, is dropped from the array entirely. A competitor added to tracking part-way through the window scores 0 for the days before it was tracked, because rollup rows exist only for runs where it was mentioned.
• An all-null response plus a `note` object means there's nothing in the rollups to draw, never that visibility is actually zero. note.code is 'NO_ROLLUP_DATA' - either nothing ran in the window, or your brand hasn't been backfilled for it, and the API can't tell those apart - or 'PRE_ROLLUP_EPOCH' (the window predates rollup coverage entirely); note.message spells out the same thing in prose.

/visibility/by-model follows the same null rule per AI model: a model with zero runs in the window returns visibilityScore: null, and averagePosition is null whenever there's no ranked mention in the window (which includes, but isn't limited to, zero runs) - never 0 for either.

Passing include_competitors=false skips the competitor lookup, but the competitors key stays in the response as an empty array - it is never dropped, so you don't have to branch on its absence.

Both endpoints have an MCP twin (get_visibility_timeseries, get_model_breakdown), but the tools are not the same code path and their payloads are shaped differently, so don't expect a field-for-field match. The REST responses expose the window as range; the MCP tools keep it named window. get_model_breakdown's five model rows do match REST's exactly. get_visibility_timeseries differs more: it returns only the days that have data (REST returns every day of the window), uses 0 where REST uses null for an unmeasured day, and lists only competitors that actually have data rather than every tracked one. Neither is capped. Where both report a value for the same day, the number is the same.

Query parameters for filtering and paging

Ninety days is the longest window the API will serve, and no all-time option exists, so anything longer has to be pulled on a schedule and stored on your side.

curl -H "X-API-Key: $API_KEY" \
  "https://www.aipeekaboo.com/api/v1/brands/$BRAND_ID/prompts?time_range=30d&search_intent=COMMERCIAL&limit=200&offset=0"

The write endpoints

A read+write key unlocks create, update, and delete across brands, prompts, competitors, and categories. The bulk routes are the reason to bother: the dashboard adds items one at a time, and these load a whole account in one call.

Field length limits are enforced server side: brand and competitor names up to 200 characters, URLs up to 500, prompt text up to 1,000, category names up to 100, and product descriptions up to 2,000. Anything longer comes back as INVALID_PARAMS rather than being silently truncated.

Error codes and what they mean

Errors come back with success: false and an error object holding a code, a human-readable message, and sometimes details.

A brand that belongs to another project returns NOT_FOUND rather than FORBIDDEN, so a 404 on an ID you believe is valid usually means the key belongs to a different project.

Rate limits by plan

Limits are counted per API key, on a per-minute window plus a daily budget that resets at midnight UTC.

Every response, not just a 429, carries the full set of counters:

Read X-RateLimit-Remaining before firing the next call and sleep until X-RateLimit-Reset when it reaches zero, rather than retrying into a wall of 429s. Starter and Peek keys hit the ceiling almost immediately, so production automations belong on Grow or higher.

Gotchas worth knowing before you build

• Prompt history uses `aiModel`, not `model`. In each /prompts/:id history entry, the model name lives in the aiModel field. Reading model returns nothing and collapses every row to "unknown".
• Prompt history caps at 100 entries. That endpoint returns the 100 most recent runs with no pagination. Since each run produces one entry per model, a daily brand only reaches back about 20 days. To keep more history, pull on a schedule and store it yourself. Check summary.truncated (with summary.historyLimit) rather than assuming a short history[] means you got everything in range: truncated: true means more runs existed than fit.
• Only `7d`, `30d`, and `90d` windows work. Any other time_range value silently falls back to 7 days rather than erroring, so a typo quietly returns the wrong window.
• `/snapshot` and `/sources` don't accept `time_range` at all. Both always return the latest analysis run regardless of any time_range you send. The response's window field is always "latest_run", and an ignoredParams: ["time_range"] array appears if you sent one, so you can tell it had no effect instead of assuming it filtered anything.
• `/competitors` is a partial exception. score, change, and rank still come only from the latest analysis run (window: "latest_run", unaffected by time_range), but time_range now sizes the window for three other per-competitor fields: visibility, sentimentPositive, and avgPosition, reported back as metricsWindow: { from, to, days, timeRange }, where from and to are YYYY-MM-DD UTC days and both ends are included, so days: 7 covers 8 dates. There is no ignoredParams on this endpoint any more, since time_range genuinely does something now.
• On `/competitors`, `null` never means zero. visibility, sentimentPositive, and avgPosition come back null when there's nothing to measure, and a note object tells you which case you're in: NO_ROLLUP_DATA (no analysis runs in the window, or the brand's history isn't built yet), PRE_ROLLUP_EPOCH (the window reaches back further than we hold data for, so ask for a shorter one), or ROLLUP_READ_FAILED (a transient read failure on our side, so retry). There's no note at all when the window is measured, and in that case a null sentimentPositive or avgPosition really does mean that competitor had no sentiment-scored or ranked run. The first two codes carry the same message text as the matching notes on the visibility endpoints; ROLLUP_READ_FAILED is unique to this one. score, change, and rank are never affected by any of this.
• `/competitors` `score` and `change` can be `null`, including for your own brand. A competitor you started tracking after the last analysis run appears right away, but with score and change null until the next run scores it. brand.score is null on the same rule when your brand has never been analysed, and summary.brandRankAmongCompetitors is then 0, a "not ranked yet" sentinel rather than a real rank. rank is its position in your live tracked list, ordered by score (ties broken by name, then id, and unscored competitors last), so adding or removing a competitor renumbers everything immediately. Competitors you've removed are dropped from /competitors, even if an older snapshot still mentioned them. /snapshot and the MCP list_competitors tool read the stored snapshot directly and still show them, which is long-standing behaviour that hasn't changed here.
• `/recommendations` is slow, so cache it. It runs a fresh model call per suggestion and can take 8 to 15 seconds. Store the result on your side instead of calling it on every page load.

Who can use it

The REST API requires an active paid subscription on any tier. It isn't available on free, no-subscription workspaces.

Local tracking

Local tracking has dedicated endpoints for existing prompts and follows your brand's rollout and plan availability. Standard snapshots, visibility scores and prompt metrics stay separate from local results.

To read results, pass a targetId from settings or its history and a model such as google-ai-mode. Use days=7, 14, 30 or 90 (default 14), or paired from and to timestamps with timezones spanning at most 90 days. Local reports use these parameters instead of time_range.

To configure tracking with a read+write key:

1. Read settings and use configuration.configVersion as expectedVersion, or 0 when configuration is null.
2. Search for a city and preview that target's coverage. Review city, state, country and unavailable model coverage and remaining capacity.
3. PUT the targetId, expectedVersion, the preview's coverageFingerprint (returned as fingerprint), and a fresh UUID idempotencyKey. If the preview requires acknowledgement, include acknowledgeCoverage: true only after accepting that coverage.
4. To pause, PUT targetId: null, the current expectedVersion and a fresh UUID. A pause needs no coverage preview.

Retry an uncertain write with the identical body and idempotency key. A version conflict means reread settings before deciding whether another write is necessary. canManage and canStopTracking reflect the current key's ability to make those changes, including write availability.

Adding city or other location fields to an ordinary prompt create or update request is rejected; create the prompt first, then use this workflow. searchIntent: "LOCAL" only classifies a prompt and does not configure tracking.

No completed analysis means brandAppearances: null, not zero. Label reports with the recorded targeting precision, preserve evidence completeness, and use a shorter window if the report exceeds 300 checks or spans different effective geographies. Local responses are private and marked no-store. Read local tracking limits and troubleshooting for the remaining bounds. The full field reference is available in Settings → Integrations → REST API, including Copy API reference for your agent.