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

# Reporting API

> Query Siteline product analytics from production systems over HTTP

<Note>
  The Reporting API is currently in **beta** and available on paid plans only. To activate it for
  your team, contact us at [team@siteline.ai](mailto:team@siteline.ai).
</Note>

The Siteline Reporting API gives production systems read-only access to product analytics, prompt performance, citations, and agent analytics traffic. Use it when you need to power internal dashboards, data pipelines, customer reporting, or agent workflows directly from Siteline data.

<Info>
  This page documents the Reporting API for reading analytics data. If you want to send pageview
  tracking events to Siteline, use the [Direct HTTP API](/integrations/http-api) instead.
</Info>

## Base URL

```text theme={null}
https://api.siteline.ai
```

All production requests must use HTTPS and return JSON.

## Authentication

Create a public API key in your Siteline workspace under **Team settings** > **Public API Key**. Only team admins can view, create, copy, or regenerate the key.

Pass the key as a bearer token:

```http theme={null}
Authorization: Bearer <public-api-key>
```

Example:

```bash theme={null}
curl \
  -H "Authorization: Bearer $SITELINE_PUBLIC_API_KEY" \
  "https://api.siteline.ai/v1/products"
```

<Warning>
  Treat the public API key as a production secret. Store it in a secret manager, never ship it to a
  browser or mobile client, and rotate it if it is exposed.
</Warning>

## Authorization model

The API key scopes every request to the Siteline team that owns the key.

* `GET /v1/products` returns only primary products owned by that team
* Product-specific routes only return data for products owned by that team
* Competitor products linked through comparison data are not authorized as primary products
* Missing keys, invalid keys, revoked keys, malformed product IDs, and unauthorized products all return the same `401` response

```json theme={null}
{ "message": "Unauthorized." }
```

## Production client checklist

* Keep requests server-side; never expose the API key to end users
* Cache low-churn discovery calls like `GET /v1/products`
* Use RFC3339 timestamps for all date ranges, for example `2026-05-01T00:00:00Z`
* Keep date windows bounded to the reporting period your workflow needs
* Retry transient `5xx` failures with exponential backoff and jitter
* Do not retry `400` or `401` responses until inputs or credentials are fixed
* Log request path, status code, and a correlation ID, but never log the full API key
* Prefer `labelIds[]`, `platforms[]`, and `groupBy` filters over downloading broad datasets and filtering later

## Query conventions

Repeated filters use bracket notation:

```text theme={null}
platforms[]=openai&platforms[]=gemini&labelIds[]=7&labelIds[]=12
```

Prompt and citation endpoints share these query parameters:

| Name          | Required | Type              | Description                                                                                                              |
| ------------- | -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `domain`      | Yes      | string            | Product domain to report metrics for, such as `example.com`.                                                             |
| `dateFrom`    | Yes      | RFC3339 timestamp | Inclusive start timestamp.                                                                                               |
| `dateTo`      | Yes      | RFC3339 timestamp | Inclusive end timestamp.                                                                                                 |
| `platforms[]` | No       | repeated string   | Platform filters. Common values include `openai`, `gemini`, `google`, `perplexity`, `google_ai_overviews`, and `claude`. |
| `labelIds[]`  | No       | repeated integer  | Prompt label IDs to filter on. Invalid IDs return `400`.                                                                 |

Invalid or missing query parameters return:

```json theme={null}
{ "message": "Invalid request parameters." }
```

## Error behavior

| Status | Response                                       | Meaning                                                |
| ------ | ---------------------------------------------- | ------------------------------------------------------ |
| `200`  | Endpoint response body                         | Request succeeded.                                     |
| `400`  | `{ "message": "Invalid request parameters." }` | Required query parameters are missing or malformed.    |
| `401`  | `{ "message": "Unauthorized." }`               | API key validation or product authorization failed.    |
| `500`  | `{ "message": "Internal server error." }`      | Unexpected server-side or upstream dependency failure. |

## Recommended sync pattern

For production ingestion jobs:

1. Call `GET /v1/products` and cache product IDs.
2. Call `GET /v1/products/{productId}/websites` and cache authorized domains.
3. Use `websiteId` on analytics timeseries requests when you need one website instead of all product websites combined.
4. Run narrow date-window requests for each product and domain.
5. Store the exact `dateFrom`, `dateTo`, endpoint path, and filters used for every sync batch.
6. On retries, re-run the same idempotent `GET` request with the same filters.

<Tip>
  Use the MCP server when an AI assistant should ask follow-up questions and choose tools
  interactively. Use the Reporting API when your own backend or data pipeline needs direct,
  repeatable access to Siteline analytics.
</Tip>