> ## 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

> REST API access to granular AI Search data for dashboards, applications and reporting workflows.

These endpoints return the same granular AI Search data enterprise marketing teams and agencies use in the platform: mentions, position, share of voice, citations, sources, prompts and competitive performance across brands and markets.

**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). Valid dimensions: `llm_service`, `llm_model`, `prompt_id`, `domain_id`, `intent`, `country`, `naics_code`, `brand` |
| `filters` | object | No | Additional filter criteria (see below) |

**Filters object:**

| Key | Type | Description |
| - | - | - |
| `llmService` | string or string\[] | Filter by AI engine (e.g. `"chatgpt"`, `"perplexity"`) |
| `llmModel` | string or string\[] | Filter by specific model |
| `promptId` | string or string\[] | Filter by prompt ID(s) |
| `intent` | string | Filter by intent type |
| `country` | string | Filter by country |
| `naicsCode` | string | Filter by NAICS industry code |

**Example — aggregated metrics:**

```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 — metrics grouped by prompt:**

Use `groupBy` with `prompt_id` to get metrics broken down per prompt instead of aggregated. To discover prompt IDs, use the [prompts endpoint](#prompts).

```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"],
    "brands": ["My Brand"],
    "groupBy": ["prompt_id"],
    "startDate": "2025-01-01",
    "endDate": "2025-01-31"
  }'
```

You can also combine `groupBy` with `filters` to narrow results to specific prompts:

```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"],
    "groupBy": ["prompt_id"],
    "filters": {
      "promptId": ["prompt_abc123", "prompt_def456"]
    }
  }'
```

**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"
  }
}
```

<Tip>
  **Per-prompt workflow:** Call `endpoint=prompts` to get prompt IDs, then use `endpoint=metrics` with `groupBy: ["prompt_id"]` to get `brand_visibility`, `citation_rate`, and other metrics for each individual prompt.
</Tip>

***

## 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). Valid dimensions: `llm_service`, `llm_model`, `prompt_id`, `domain_id`, `intent`, `country`, `naics_code` |
| `filters` | object | No | Additional filter criteria (see below) |
| `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) |

**Filters object:**

| Key | Type | Description |
| - | - | - |
| `llmService` | string or string\[] | Filter by AI engine |
| `llmModel` | string or string\[] | Filter by specific model |
| `promptId` | string or string\[] | Filter by prompt ID(s) |
| `intent` | string | Filter by intent type |
| `country` | string | Filter by country |

**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). Valid dimensions: `llm_service`, `llm_model`, `prompt_id`, `domain_id`, `country`, `topic`, `language` |
| `filters` | object | No | Additional filter criteria (see below) |
| `topN` | number | No | Max results (default: 100) |
| `aggregateBy` | string | No | `domain` (default) or `url` |
| `includeUrls` | boolean | No | Include URL-level data (default: true) |

**Filters object:**

| Key | Type | Description |
| - | - | - |
| `llmService` | string or string\[] | Filter by AI engine |
| `llmModel` | string or string\[] | Filter by specific model |
| `promptId` | string or string\[] | Filter by prompt ID(s) |
| `domain` | string | Filter by cited domain (partial match) |
| `country` | string | Filter by country |
| `topic` | string | Filter by topic |

**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). Valid dimensions: `llm_service`, `llm_model`, `prompt_id`, `domain_id`, `country`, `naics_code`, `standardized_topic`, `business_type` |
| `filters` | object | No | Additional filter criteria (see below) |
| `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) |

**Filters object:**

| Key | Type | Description |
| - | - | - |
| `llmService` | string or string\[] | Filter by AI engine |
| `intent` | string | Filter by intent type |
| `userJourneyStage` | string | Filter by user journey stage |
| `category` | string | Filter by category |
| `country` | string | Filter by country |
| `naicsCode` | string | Filter by NAICS industry code |

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `query` | string | The search query text |
| `prompt_count` | number | Number of prompts associated with this query |
| `last_updated` | string | Timestamp of the most recent data |
| `brands_mentioned` | number | Total number of distinct brands detected in the AI responses for this query — includes **all** brands (yours, competitors, and others), not only your own |

<Info>
  `brands_mentioned` counts every distinct brand, product, or service name found in the AI-generated response text. For example, if a response mentions your brand plus three competitors, `brands_mentioned` is 4.
</Info>

**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 extended metadata fields (default: true) |

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `promptId` | string | Unique identifier for the prompt. Use this with `groupBy` or `filters.promptId` on other endpoints. |
| `promptText` | string | The prompt text |
| `status` | string | Current status (`active`, `paused`, etc.) |
| `intent` | string | Detected intent type |
| `category` | string | Prompt category |
| `labels` | string\[] | Labels assigned to this prompt |
| `createdAt` | string | ISO 8601 creation timestamp |
| `lastRunAt` | string | ISO 8601 timestamp of the last analysis run |
| `domainId` | string | The brand (domain) this prompt belongs to |

When `includeMetadata` is `true`, additional fields are returned: `userJourneyStage`, `commercial`, `source`, `naicsCode`, `country`.

**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
  }'
```

**Response:**

```json theme={null}
{
  "success": true,
  "endpoint": "prompts",
  "data": [
    {
      "promptId": "abc123",
      "promptText": "What is the best project management tool?",
      "status": "active",
      "intent": "informational",
      "category": "software",
      "labels": ["product", "comparison"],
      "createdAt": "2025-01-15T10:30:00.000Z",
      "lastRunAt": "2025-01-31T08:00:00.000Z",
      "domainId": "domain_xyz"
    }
  ],
  "metadata": { ... }
}
```

<Tip>
  Use `promptId` from this endpoint to filter or group data on the `metrics`, `brands`, `citations`, and `queries` endpoints — for example, `groupBy: ["prompt_id"]` or `filters: { "promptId": ["abc123"] }`.
</Tip>

***

## 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 (see below) |
| `sortBy` | string | No | `createdAt` (default) or `promptId` |
| `topN` | number | No | Max results (default: 100) |
| `includeFullText` | boolean | No | Include full response text (default: false) |

**Filters object:**

| Key | Type | Description |
| - | - | - |
| `llmService` | string or string\[] | Filter by AI engine |
| `llmModel` | string or string\[] | Filter by specific model |
| `promptId` | string or string\[] | Filter by prompt ID(s) |
| `brandMentioned` | boolean | Only responses where your brand is/isn't mentioned |
| `websiteCited` | boolean | Only responses where your website is/isn't cited |
| `intent` | string | Filter by intent type |
| `country` | string | Filter by country |

**Response fields:**

| Field | Type | Description |
| - | - | - |
| `promptId` | string | The prompt this response belongs to |
| `promptText` | string | The prompt text |
| `answerText` | string | The AI-generated response text (when `includeFullText` is true) |
| `llmService` | string | AI engine that generated the response (e.g. `"chatgpt"`, `"perplexity"`) |
| `llmModel` | string | Specific model used |
| `brandMentioned` | boolean | Whether your brand was mentioned in this response |
| `websiteCited` | boolean | Whether your website was cited in this response |
| `brands` | string\[] | All brands detected in the response text (yours, competitors, and others) |
| `citations` | object\[] | Citations found in the response, each with `url` and `cited` fields |

**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"]
}
```


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