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

# API Endpoints

> Available REST API endpoints for accessing your Superlines data.

**Base URL:** `https://api.superlines.io`

All requests require [authentication](/api/authentication) via Bearer token. The API supports both **GET** (query parameters) and **POST** (JSON body) requests.

Every request includes an `endpoint` parameter that selects which data to return. Your API key determines which brands (domains) are accessible — you can optionally narrow results with the `brands` parameter.

<Info>
  Your API key is scoped to your organization. If you omit the `brands` parameter, data for **all** brands in your organization is returned.
</Info>

## Common parameters

These parameters are shared across most endpoints.

| Parameter   | Type                | Required | Description                                                                                 |
| ----------- | ------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `endpoint`  | string              | Yes      | Which data to retrieve: `metrics`, `brands`, `citations`, `queries`, `prompts`, `responses` |
| `brands`    | string or string\[] | No       | Filter by brand name(s). Omit to include all brands in your organization.                   |
| `labels`    | string or string\[] | No       | Filter by prompt label(s). Only data for prompts with these labels is returned.             |
| `startDate` | string              | No       | Start date (`YYYY-MM-DD`)                                                                   |
| `endDate`   | string              | No       | End date (`YYYY-MM-DD`)                                                                     |

***

## Metrics

### `endpoint=metrics`

Retrieve core performance metrics for your brands.

| Parameter     | Type                | Required | Description                                                                                                                                          |
| ------------- | ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `metrics`     | string or string\[] | **Yes**  | Comma-separated or array: `brand_visibility`, `citation_rate`, `citations`, `share_of_citations`, `share_of_voice`, `mentions`, `tests`, `responses` |
| `brands`      | string or string\[] | No       | Filter by brand name(s)                                                                                                                              |
| `labels`      | string or string\[] | No       | Filter by prompt label(s)                                                                                                                            |
| `startDate`   | string              | No       | Start date (`YYYY-MM-DD`)                                                                                                                            |
| `endDate`     | string              | No       | End date (`YYYY-MM-DD`)                                                                                                                              |
| `granularity` | string              | No       | `total` (default), `daily`, `weekly`, `monthly`                                                                                                      |
| `groupBy`     | string or string\[] | No       | Group results by dimension(s)                                                                                                                        |
| `filters`     | object              | No       | Additional filter criteria                                                                                                                           |

**Example (POST):**

```bash theme={null}
curl -X POST https://api.superlines.io \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "metrics",
    "metrics": ["brand_visibility", "citation_rate", "share_of_voice"],
    "brands": ["My Brand"],
    "startDate": "2025-01-01",
    "endDate": "2025-01-31",
    "granularity": "weekly"
  }'
```

**Example (GET):**

```bash theme={null}
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.superlines.io?endpoint=metrics&metrics=brand_visibility,citation_rate&brands=My+Brand&startDate=2025-01-01&endDate=2025-01-31&granularity=weekly"
```

**Response:**

```json theme={null}
{
  "success": true,
  "endpoint": "metrics",
  "data": [ ... ],
  "metadata": {
    "metrics": ["brand_visibility", "citation_rate", "share_of_voice"],
    "brands": ["My Brand"],
    "dateRange": {
      "startDate": "2025-01-01",
      "endDate": "2025-01-31"
    },
    "granularity": "weekly",
    "totalRows": 4,
    "executionTime": "320ms"
  }
}
```

***

## Brand mentions

### `endpoint=brands`

Get brand mention data with sentiment and share of voice.

| Parameter             | Type                | Required | Description                                     |
| --------------------- | ------------------- | -------- | ----------------------------------------------- |
| `brands`              | string or string\[] | No       | Filter by brand name(s)                         |
| `labels`              | string or string\[] | No       | Filter by prompt label(s)                       |
| `startDate`           | string              | No       | Start date (`YYYY-MM-DD`)                       |
| `endDate`             | string              | No       | End date (`YYYY-MM-DD`)                         |
| `granularity`         | string              | No       | `total` (default), `daily`, `weekly`, `monthly` |
| `groupBy`             | string or string\[] | No       | Group results by dimension(s)                   |
| `filters`             | object              | No       | Additional filter criteria                      |
| `topN`                | number              | No       | Max brands to return (default: 50)              |
| `includeSentiment`    | boolean             | No       | Include sentiment data (default: true)          |
| `includeShareOfVoice` | boolean             | No       | Include SOV data (default: true)                |
| `minMentions`         | number              | No       | Minimum mention count to include (default: 1)   |

**Example:**

```bash theme={null}
curl -X POST https://api.superlines.io \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "brands",
    "brands": ["My Brand"],
    "startDate": "2025-01-01",
    "endDate": "2025-01-31",
    "groupBy": ["brand"],
    "includeSentiment": true
  }'
```

***

## Citations

### `endpoint=citations`

Get citation data at domain or URL level.

| Parameter     | Type                | Required | Description                                     |
| ------------- | ------------------- | -------- | ----------------------------------------------- |
| `brands`      | string or string\[] | No       | Filter by brand name(s)                         |
| `labels`      | string or string\[] | No       | Filter by prompt label(s)                       |
| `startDate`   | string              | No       | Start date (`YYYY-MM-DD`)                       |
| `endDate`     | string              | No       | End date (`YYYY-MM-DD`)                         |
| `granularity` | string              | No       | `total` (default), `daily`, `weekly`, `monthly` |
| `groupBy`     | string or string\[] | No       | Group results by dimension(s)                   |
| `filters`     | object              | No       | Additional filter criteria                      |
| `topN`        | number              | No       | Max results (default: 100)                      |
| `aggregateBy` | string              | No       | `domain` (default) or `url`                     |
| `includeUrls` | boolean             | No       | Include URL-level data (default: true)          |

**Example:**

```bash theme={null}
curl -X POST https://api.superlines.io \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "citations",
    "brands": ["My Brand"],
    "aggregateBy": "url",
    "startDate": "2025-01-01",
    "endDate": "2025-01-31",
    "topN": 50
  }'
```

***

## Queries

### `endpoint=queries`

Get search query data associated with your tracked prompts.

| Parameter         | Type                | Required | Description                           |
| ----------------- | ------------------- | -------- | ------------------------------------- |
| `brands`          | string or string\[] | No       | Filter by brand name(s)               |
| `promptId`        | string              | No       | Filter by a specific prompt ID        |
| `groupBy`         | string or string\[] | No       | Group results by dimension(s)         |
| `filters`         | object              | No       | Additional filter criteria            |
| `topN`            | number              | No       | Max results (default: 100)            |
| `sortBy`          | string              | No       | `prompts` (default) or `query`        |
| `minVolume`       | number              | No       | Minimum volume threshold (default: 0) |
| `includeMetadata` | boolean             | No       | Include metadata (default: true)      |

**Example:**

```bash theme={null}
curl -X POST https://api.superlines.io \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "queries",
    "brands": ["My Brand"],
    "sortBy": "prompts",
    "topN": 50
  }'
```

***

## Prompts

### `endpoint=prompts`

List tracked prompts for your brands.

| Parameter         | Type                | Required | Description                                      |
| ----------------- | ------------------- | -------- | ------------------------------------------------ |
| `brands`          | string or string\[] | No       | Filter by brand name(s)                          |
| `status`          | string or string\[] | No       | Filter by status: `active`, `paused`, etc.       |
| `intent`          | string or string\[] | No       | Filter by intent type                            |
| `labels`          | string or string\[] | No       | Filter by label(s)                               |
| `sortBy`          | string              | No       | `createdAt` (default), `lastRunAt`, `promptText` |
| `topN`            | number              | No       | Max results (default: 100)                       |
| `includeMetadata` | boolean             | No       | Include metadata (default: true)                 |

**Example:**

```bash theme={null}
curl -X POST https://api.superlines.io \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "prompts",
    "brands": ["My Brand"],
    "status": "active",
    "topN": 50
  }'
```

***

## Responses

### `endpoint=responses`

Get raw AI response data for your tracked prompts.

| Parameter         | Type                | Required | Description                                 |
| ----------------- | ------------------- | -------- | ------------------------------------------- |
| `brands`          | string or string\[] | No       | Filter by brand name(s)                     |
| `labels`          | string or string\[] | No       | Filter by prompt label(s)                   |
| `startDate`       | string              | No       | Start date (`YYYY-MM-DD`)                   |
| `endDate`         | string              | No       | End date (`YYYY-MM-DD`)                     |
| `filters`         | object              | No       | Additional filter criteria                  |
| `sortBy`          | string              | No       | `createdAt` (default) or `promptId`         |
| `topN`            | number              | No       | Max results (default: 100)                  |
| `includeFullText` | boolean             | No       | Include full response text (default: false) |

**Example:**

```bash theme={null}
curl -X POST https://api.superlines.io \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "responses",
    "brands": ["My Brand"],
    "startDate": "2025-01-01",
    "endDate": "2025-01-31",
    "includeFullText": true,
    "topN": 20
  }'
```

***

## Rate limits

| Plan       | Requests/minute |
| ---------- | --------------- |
| Starter    | 60              |
| Growth     | 120             |
| Enterprise | 300             |

Exceeding the rate limit returns a `429` status code with `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers. Implement exponential backoff in your integration.

## Response format

All successful responses follow this structure:

```json theme={null}
{
  "success": true,
  "endpoint": "metrics",
  "data": [ ... ],
  "metadata": {
    "brands": ["My Brand"],
    "dateRange": { "startDate": "2025-01-01", "endDate": "2025-01-31" },
    "totalRows": 42,
    "executionTime": "215ms"
  }
}
```

Error responses:

```json theme={null}
{
  "error": "Invalid endpoint parameter",
  "message": "Endpoint must be one of: metrics, brands, citations, queries, prompts, responses",
  "validEndpoints": ["metrics", "brands", "citations", "queries", "prompts", "responses"]
}
```