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, and recommended prompts.
• Read+write keys can also create, update, and delete brands, prompts, competitors, and categories.

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
    }
  },
  "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.

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.
• 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.
• `/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.