API docs v1

Scheduled reports

How brands, scheduled reports, region configs and prompts fit together to power recurring AI visibility tracking.

Recurring AI visibility tracking in Rank Prompt is built on a four-level hierarchy: brand → scheduled report → region config → prompts. Once you understand how the four resources nest, the rest of the API is just CRUD.

This page is a conceptual overview. For the exact request shapes, jump to the Scheduled reports and Region configs sections of the reference.

The hierarchy

brand
└── scheduled report           (cadence: daily / weekly / monthly)
    └── region config (×N)     (one per market: country + language + AI platforms)
        └── prompts (×M)       (the questions we ask each AI platform)

Every tick of the scheduler materialises one report per active region config attached to the schedule. So a weekly schedule with 3 region configs produces 3 fresh reports every week, each containing the prompts seeded on its region config.

Brand

A brand is the top-level container for everything we track. It owns its researched facts, its categories, the aliases the analyzer counts as brand mentions, and every report (one-off or recurring) below it. See POST /v1/brands.

Scheduled report

A scheduled report defines the cadence at which we want to refresh visibility data:

  • frequency: daily, weekly or monthly.
  • next_run_at: computed from frequency on creation; you can override it via PATCH to anchor a run to a specific moment.
  • is_active: pause/resume without deleting history.

A schedule by itself doesn’t ask any questions yet; it’s the cadence container. You attach region configs to it to define what it actually runs. See POST /v1/scheduled-reports.

Manual runs

You can fire a schedule outside its normal cadence with POST /v1/scheduled-reports/{id}/executions. By default it runs every active region config attached to the schedule; pass region_config_id to scope the run to one. Manual runs do not advance next_run_at.

Region config

A region config is one market you want to track on a given schedule:

  • country: the market (e.g. United States).
  • language: the language we ask the AI platforms in.
  • location: optional finer-grained locality (e.g. Manhattan).
  • ai_platforms: which models to query (chatgpt, claude, perplexity, …).
  • scheduled_report_id: required. The schedule this region belongs to.

Region configs live under /v1/region-configs (not nested under a schedule) because they are first-class resources you may want to:

  • list across a brand for analytics,
  • attach/detach independently of their parent schedule,
  • or copy from a previous one when expanding to a new market.

Each schedule is capped at 20 active region configs.

Attaching, re-attaching, removing

There are three patterns:

You want to…Endpoint
Create a new region config under a schedulePOST /v1/region-configs with scheduled_report_id set
Move an existing region config to a different schedulePOST /v1/scheduled-reports/{id}/region-configs/{rc_id}
Remove a region from a scheduleDELETE /v1/region-configs/{rc_id} (cascades to prompts and history)

There is intentionally no detach endpoint: the region_configs.scheduled_report_id column is NOT NULL, so a region config cannot exist “unlinked”. To take a region out of a schedule, delete the region config, or move it to a different schedule with the attach endpoint.

Prompts

The leaf level. Each prompt is a single question we’ll ask every AI platform on the region config:

{
  "prompt_text": "best CRM for SaaS startups",
  "category": "CRM Software"
}

category is required: pick a stable free-form bucket that names the topic the prompt is about (e.g. CRM Software, Marketing Automation, Specialty Coffee). It powers the per-category breakdowns surfaced in schedule analytics, so two prompts about the same topic should share the same category. Prompts are bulk-managed under POST /v1/region-configs/{id}/prompts; each region config is capped at 50 active prompts.

Prompts on a region config are soft-deleted: deleting a prompt sets disabled=true so it stops appearing in future runs while past reports remain unchanged. To wipe all active prompts at once and re-seed, use DELETE /v1/region-configs/{id}/prompts.

Putting it together

Setting up a brand-new weekly schedule for two markets:

# 1. Create the schedule (no regions yet, it's just the cadence)
curl -X POST https://api.rankprompt.com/v1/scheduled-reports \
  -H "Authorization: Bearer rp_live_YOUR_KEY" \
  -H "Idempotency-Key: schedule-acme-weekly" \
  -d '{"brand_id": "{brand_id}", "name": "Weekly tracking", "frequency": "weekly"}'

# 2. Add a US region config under it
curl -X POST https://api.rankprompt.com/v1/region-configs \
  -H "Authorization: Bearer rp_live_YOUR_KEY" \
  -H "Idempotency-Key: rc-acme-us" \
  -d '{
    "brand_id": "{brand_id}",
    "scheduled_report_id": "{schedule_id}",
    "name": "United States",
    "country": "United States",
    "language": "en",
    "ai_platforms": ["chatgpt", "perplexity"]
  }'

# 3. Add a UK region config under the same schedule
curl -X POST https://api.rankprompt.com/v1/region-configs \
  -H "Authorization: Bearer rp_live_YOUR_KEY" \
  -H "Idempotency-Key: rc-acme-uk" \
  -d '{
    "brand_id": "{brand_id}",
    "scheduled_report_id": "{schedule_id}",
    "name": "United Kingdom",
    "country": "United Kingdom",
    "language": "en",
    "ai_platforms": ["chatgpt", "perplexity"]
  }'

# 4. Seed prompts on each region config (category is required: use the topic)
curl -X POST https://api.rankprompt.com/v1/region-configs/{us_rc_id}/prompts \
  -H "Authorization: Bearer rp_live_YOUR_KEY" \
  -d '{"prompts": [
    {"prompt_text": "best CRM for SaaS startups", "category": "CRM Software"},
    {"prompt_text": "alternatives to Salesforce", "category": "CRM Software"}
  ]}'

# 5. (Optional) Run it now instead of waiting for the next tick
curl -X POST https://api.rankprompt.com/v1/scheduled-reports/{schedule_id}/executions \
  -H "Authorization: Bearer rp_live_YOUR_KEY" \
  -H "Idempotency-Key: run-schedule-once" \
  -d '{}'

After that, every weekly tick produces two reports (one per region config) that you can list with GET /v1/reports?scheduled_report_id={schedule_id} or analyse in aggregate via GET /v1/scheduled-reports/{id}/analytics.

Reading what came back

Three lenses, depending on what you want to render:

  • Per-run reports: GET /v1/reports?scheduled_report_id={schedule_id} returns one report per region config per tick, each with prompts and per-platform results inlined.
  • Schedule analytics: GET /v1/scheduled-reports/{id}/analytics rolls every completed run into average visibility, per-prompt sparklines, and per-AI-platform appearance rates.
  • Per-prompt history: GET /v1/scheduled-reports/{id}/prompt-history/{region_config_prompt_id} returns one entry per run for a single prompt, perfect for time-series charts of how a question’s visibility evolves.

Lifecycle gotchas

  • Deleting a brand cascades to its schedules, region configs, prompts and reports. Irreversible.
  • Deleting a schedule deletes the linked reports and their prompts; the region configs are removed with it.
  • Deleting a region config cascades to its prompts and historical reports for that region.
  • Disabling a region config (PATCH ... is_active=false) keeps the data but stops future ticks from running it.
  • Manual runs (POST .../executions) don’t advance next_run_at.