> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rankraft.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cookbook

> Working recipes that rebuild the RankRaft dashboard's numbers from the API, in JavaScript, Python and curl.

Each recipe answers one question — "what is our Visibility Score this month, and how did it move?", "which domains do the engines cite most?" — with code you can paste and run. Every number a recipe prints is the number the dashboard shows for the same site, range and filters, because the API and the dashboard share one scoring library.

## What you'll need

* An **Enterprise** plan. The REST API is Enterprise only; on Basic and Growth, the [MCP server](/mcp/introduction) answers the same questions inside Claude, ChatGPT and other assistants.
* An **API key**. Create one under **API & AI assistants** in the dashboard (owners only). It starts with `rr_api_` and is shown once.
* The **SDK** for your language, or nothing at all for curl.

## One-time setup

```bash JavaScript theme={"system"}
npm install rankraft-js
export RANKRAFT_API_KEY=rr_api_...
```

```bash Python theme={"system"}
pip install rankraft-py            # 'rankraft-py[pandas]' adds .to_pandas()
export RANKRAFT_API_KEY=rr_api_...
```

```bash curl theme={"system"}
export RANKRAFT_API_KEY=rr_api_...
curl https://api.rankraft.ai/v1/me -H "X-API-Key: $RANKRAFT_API_KEY"
```

Both SDKs read `RANKRAFT_API_KEY` from the environment, retry rate-limited requests after the exact `Retry-After` time, and page through results for you. Packages: [rankraft-js on npm](https://www.npmjs.com/package/rankraft-js) · [rankraft-py on PyPI](https://pypi.org/project/rankraft-py/).

Most recipes need a `site_id`. [Find your site ID](/cookbook/find-your-site-id) once and export it as `RANKRAFT_SITE_ID`.

## Give your AI assistant context

These docs are published as plain text at [docs.rankraft.ai/llms.txt](https://docs.rankraft.ai/llms.txt). Paste that link into Claude, ChatGPT or Cursor before asking it to write code against the API. In a coding agent, the [RankRaft skill](/skills/rankraft-skill) or the [Claude Code plugin](/skills/claude-code-plugin) does the same job and knows the conventions below.

## Before you build anything

Read [Conventions & gotchas](/cookbook/conventions). Three rules cause most wrong numbers:

1. **Dates are inclusive UTC days.** `start_date: "2026-09-01"`, `end_date: "2026-09-30"` is all of September.
2. **Never average daily rows into a period score.** Ask for the period in one call instead.
3. **Changes are computed by you**, from two calls over two windows of equal length.

## Recipes

### Get started

> **[Conventions & gotchas](/cookbook/conventions)**
>
> Dates, scales, pagination and the mistakes that produce plausible wrong numbers.

> **[Data model](/cookbook/data-model)**
>
> Organization, sites, brands, prompts, engines and answers.

> **[Endpoints at a glance](/cookbook/endpoints-at-a-glance)**
>
> Every endpoint, its metrics, groupings and filters on one page.

> **[Find your site ID](/cookbook/find-your-site-id)**
>
> The one ID every report needs.

> **[Your brand, domains and competitors](/cookbook/brand-and-competitors)**
>
> Who counts as you, and who counts as a competitor.

### Metrics

> **[How metrics are calculated](/cookbook/how-metrics-are-calculated)**
>
> Every formula, a worked example, and how to reproduce it from raw answers.

> **[Why past numbers change](/cookbook/why-past-numbers-change)**
>
> What is stored once, and what is applied fresh on every request.

### Visibility

> **[Visibility Score with change](/cookbook/visibility-score)**
>
> This period's score and its change against the previous one.

> **[Headline and daily together](/cookbook/headline-and-daily)**
>
> A headline figure and its daily trend, and why they differ.

> **[Visibility over time](/cookbook/visibility-over-time)**
>
> Daily, weekly or monthly trend lines.

> **[Competitor leaderboard](/cookbook/competitor-leaderboard)**
>
> Rank yourself against your confirmed competitors.

> **[Compare competitors over time](/cookbook/compare-competitors)**
>
> One line per brand, day by day.

> **[Segment by engine, category or prompt](/cookbook/segment-visibility)**
>
> Where you are strong and where you are missing.

### Citations

> **[Owned citation share with change](/cookbook/owned-citation-share)**
>
> How much of what the engines cite is your own site.

> **[Citation share and volume over time](/cookbook/citation-share-over-time)**
>
> Two daily series from one call.

> **[Citation rank by domain](/cookbook/citation-rank)**
>
> Top cited domains with their change in points.

> **[Where AI gets its answers](/cookbook/citation-sources)**
>
> Third-party sources worth getting onto.

### More recipes

> **[Manage prompts from a CSV](/cookbook/prompts-from-csv)**
>
> Sync a prompt list from a spreadsheet, with a dry run first.

> **[AI crawler traffic to a warehouse](/cookbook/bot-traffic-to-warehouse)**
>
> A daily export of crawler hits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.