# Docs

- [Introduction](/): Omnia developer documentation — REST API and MCP Server for querying AI visibility data, brand citations, share of voice, and sentiment across ChatGPT, Perplexity, and Google AI Overviews.
- REST API
  - [Overview](/api): Omnia REST API reference — programmatically query AI visibility metrics, brand share of voice, citations, and sentiment across ChatGPT, Perplexity, Google AI Overviews, and more.
  - [Authentication](/api/authentication)
  - [Responses](/api/responses)
  - [Pagination](/api/pagination)
  - [Rate limiting](/api/rate-limiting)
  - [Async operations](/api/async-operations)
  - [Versioning](/api/versioning)

  - **Guides**
  - [Export performance data](/api/guides/export-performance-data)

  - **Endpoints**
  - AI Answer
    - [Get AI answer](/api/ai-answer/get-ai-answer): Retrieve one AI answer by its id: the full response an AI engine gave to a monitored prompt, with the sources it cited. Use it to read the wording behind a metric or a citation.
    - [List AI answers](/api/ai-answer/list-ai-answers): Retrieve a paginated list of AI answers for the given prompt. Pagination in this endpoint is not 100% accurate and pages might have fewer items than initially requested. For the same reason, the real total number of items can be lower than the one reported in responses
  - Brand
    - [Create brand](/api/brand/create-brand): Create a new brand with the provided details. The brand will be associated with the authenticated organization.
    - [Delete brand](/api/brand/delete-brand): Delete a brand and all its associated data including topics and prompts. This action cannot be undone.
    - [Get brand](/api/brand/get-brand): Retrieve one brand by its id, with its domain, alternative names, markets and tracked competitors. Use it to turn a brand id into the brand details the analytics endpoints report on.
    - [List brands](/api/brand/list-brands): Retrieve a paginated list of brands. Optionally filter by domain or name using partial, case-insensitive matching.
    - [Update brand](/api/brand/update-brand): Update an existing brand. Only the fields provided in the request body will be updated.
    - Performance
      - [Create metrics export task](/api/brand/performance/create-metrics-export-task): Schedule an asynchronous export task that writes the resulting **ZIP archive** to cloud storage and exposes it as a presigned download URL. Use this variant when you don't want to keep an HTTP connection open for the duration of the export (for example, for scheduled jobs, very large date ranges, or background pipelines) or when you need files ready to load into BI tools like Looker Studio, BigQuery or Tableau. The request body is empty; all parameters are passed as query parameters. The date range and the engine filter behave exactly as on the streaming `GET` variant. Where the `GET` takes a single `entity` and `metric`, this endpoint takes comma-separated `entities` and `metrics` so one task can cover several granularities and metrics at once, plus a `format` selecting how each file is serialized. The archive holds **one file per requested `entities` × `metrics` combination**, named `<entity>_<metric>.<format>` — for example `prompt_share-of-voice.ndjson`. If any individual query fails, the archive also contains an `errors.json` listing the combinations that could not be produced, and the task reports `status: "failed"`. `format` selects how each file is serialized: - `ndjson` (default) — one JSON object per line, matching the `ExportRow` shape documented on the streaming endpoint. Fields that have no value are omitted from the line. - `csv` — a header row followed by one row per record. The columns are the `ExportRow` fields for the requested entity and metric, sorted alphabetically and identical on every row; a field with no value is written as an empty cell. Columns are fixed by the schema, so the header is present even when the export contains no rows. The response is `202 Accepted` with `links.self` pointing at the polling endpoint (`GET /api/v1/exports/{export}`). Poll that URL until the `status` becomes `completed` (or `failed`). When the export completes, the polling response includes a `resultsUrl`, a presigned URL that lets you download the archive. Presigned URLs expire 7 days after generation.
      - [Get citations aggregates](/api/brand/performance/get-citations-aggregates): Retrieve the web sources cited by the AI answers to a brand's monitored prompts over a date range, with how often each source is cited. Use it to find which pages AI engines draw on when they answer.
      - [Get citations time series](/api/brand/performance/get-citations-time-series): Retrieve time series data showing citations evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range.
      - [Get metrics export](/api/brand/performance/get-metrics-export): Retrieve the status of a metrics export task. When the export has finished successfully, the response includes a presigned URL to download the results as a ZIP archive, holding one file per exported entity and metric in the `format` requested when the task was created. While the task is in progress, the response includes a `Retry-After` header suggesting when to poll again.
      - [Get sentiment aggregates](/api/brand/performance/get-sentiment-aggregates): Retrieve a flat, paginated list of sentiment aggregates. Each row represents a unique brand-feature pair with counts of endorsed, undermined, and neutral feature mentions.
      - [Get sentiment time series](/api/brand/performance/get-sentiment-time-series): Retrieve daily sentiment distribution over time for the owned brand only (competitors are not included). Returns counts of endorsed, undermined, and neutral feature mentions per day within the specified date range.
      - [Get share of voice aggregates](/api/brand/performance/get-share-of-voice-aggregates): Retrieve share of voice for a brand and its competitors over a date range: the portion of all brand mentions in the AI answers to the brand's monitored prompts that each brand holds. Use it to compare brands against each other for a period.
      - [Get share of voice time series](/api/brand/performance/get-share-of-voice-time-series): Retrieve time series data showing share of voice evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range.
      - [Get visibility aggregates](/api/brand/performance/get-visibility-aggregates): Retrieve visibility for a brand and its competitors over a date range: the share of the brand's monitored prompts whose AI answers mention each brand. Use it to see how often a brand appears at all for a period.
      - [Get visibility time series](/api/brand/performance/get-visibility-time-series): Retrieve time series data showing visibility evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range.
      - [Stream metrics export](/api/brand/performance/stream-metrics-export): Stream every row of the selected metric for the given brand. Changing `entity` cascades entity information onto each row: brand-level exports carry only brand fields, topic-level exports also include the topic, and prompt-level exports also include the prompt. If you can't keep an HTTP connection open for the duration of the export (for example, for scheduled jobs, very large date ranges, or background pipelines), use `POST /api/v1/brands/{brand}/export` instead and poll for completion.
  - Insight
    - [Get insight](/api/insight/get-insight): Retrieve one insight by its id, with its full text and the prompt it was generated from. Use it to read an insight a list call referred to.
    - [List insights](/api/insight/list-insights): Retrieve the insights generated for a brand's prompts, newest first. Use it to read the written explanations of why the brand performs the way it does, rather than the metrics themselves.
    - [Update insight](/api/insight/update-insight): Change the status of one insight. Use it to record that a caller has acted on an insight or no longer wants to see it.
    - Generation
      - [Generate insights](/api/insight/generation/generate-insights): Starts a new insights generation task.
      - [Get insight generation](/api/insight/generation/get-insight-generation): Retrieve an insight generation by its id. This method is used to poll ongoing generations.
  - Prompt
    - [Create prompt](/api/prompt/create-prompt): Creates a new non-monitored prompt that depends on the selected topic. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `POST /api/v1/brands/{brand}/prompts` instead. It does not require a topic ID.
    - [Create prompts](/api/prompt/create-prompts): Bulk-create prompts for a brand. Each prompt is grouped under the named topic, or an auto-managed topic for the given location if no topic name is provided. Returns a report detailing created prompts, skipped duplicates, and row-level errors.
    - [Delete prompt](/api/prompt/delete-prompt): Permanently delete one prompt and the AI answers collected for it. Use it when the prompt should no longer be tracked or kept; this cannot be undone. Turning monitoring off keeps the prompt and its history while stopping collection.
    - [Get prompt](/api/prompt/get-prompt): Retrieve one prompt by its id, with its text, type, country, tags and monitoring status. Use it to turn a prompt id into the prompt's own configuration.
    - [List brand prompts](/api/prompt/list-brand-prompts): Retrieve every prompt monitored for a brand, with its text, type, country, tags and monitoring status. Use it to find the prompt a caller is asking about, or to review what the brand currently tracks.
    - [List prompts](/api/prompt/list-prompts): Retrieve a paginated list of prompts. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/prompts` instead. It does not require a topic ID and supports `type`, `countries`, and `tags` filters to narrow the results.
    - [Toggle prompt monitoring](/api/prompt/toggle-prompt-monitoring): Changes the monitoring status for a prompt.
    - [Update prompt](/api/prompt/update-prompt): Update an existing prompt. Only the fields provided in the request body will be updated.
    - Performance
      - [Get citations aggregates](/api/prompt/performance/get-citations-aggregates): Retrieve the web sources cited by one prompt's AI answers over a date range, with how often each source is cited. Use it to find which pages AI engines draw on for that prompt.
      - [Get citations time series](/api/prompt/performance/get-citations-time-series): Retrieve prompt time series data showing citations evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range.
      - [Get sentiment aggregates](/api/prompt/performance/get-sentiment-aggregates): Retrieve a flat, paginated list of sentiment aggregates for a prompt. Each row represents a unique brand-feature pair with counts of endorsed, undermined, and neutral feature mentions.
      - [Get sentiment time series](/api/prompt/performance/get-sentiment-time-series): Retrieve daily sentiment distribution over time for the owned brand within a prompt (competitors are not included). Returns counts of endorsed, undermined, and neutral feature mentions per day within the specified date range.
      - [Get share of voice aggregates](/api/prompt/performance/get-share-of-voice-aggregates): Retrieve share of voice for the brands mentioned in one prompt's AI answers over a date range: the portion of all brand mentions each brand holds. Use it to compare brands within a single prompt.
      - [Get share of voice time series](/api/prompt/performance/get-share-of-voice-time-series): Retrieve prompt time series data showing share of voice evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range.
      - [Get visibility aggregates](/api/prompt/performance/get-visibility-aggregates): Retrieve visibility for the brands mentioned in one prompt's AI answers over a date range: the share of that prompt's answers mentioning each brand. Use it to see who appears in a single prompt.
      - [Get visibility time series](/api/prompt/performance/get-visibility-time-series): Retrieve prompt time series data showing visibility evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range.
  - Topic
    - [Bulk import prompts](/api/topic/bulk-import-prompts): Bulk-import prompts from parsed CSV rows. Rows missing a topic are grouped via automatic topic discovery. Returns a report detailing created topics, skipped duplicates, and row-level errors. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `POST /api/v1/brands/{brand}/prompts` instead.
    - [Create topic](/api/topic/create-topic): Creates a new non-monitored topic with associated prompts. If a topic with the same name and location already exists for this brand, the prompts will be added to the existing topic instead. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `POST /api/v1/brands/{brand}/prompts` instead.
    - [Delete topic](/api/topic/delete-topic): Delete a topic and all its associated data including prompts. This action cannot be undone. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `DELETE /api/v1/prompts/{prompt}` to delete individual prompts instead.
    - [Get topic](/api/topic/get-topic): Retrieve a topic by its id. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/prompts` instead. It returns all prompts for the brand and supports `type`, `countries`, and `tags` filters to narrow the results.
    - [List topics](/api/topic/list-topics): Retrieve a paginated list of topics. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/prompts` instead. It returns all prompts for the brand and supports `type`, `countries`, and `tags` filters to narrow the results.
    - [Toggle topic monitoring](/api/topic/toggle-topic-monitoring): Changes the monitoring status for a topic and all its prompts. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `PUT /api/v1/prompts/{prompt}/toggle-monitoring` to toggle monitoring for individual prompts instead.
    - [Update topic](/api/topic/update-topic): Update an existing topic. Only the fields provided in the request body will be updated. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `PATCH /api/v1/prompts/{prompt}` to update individual prompts instead.
    - Performance
      - [Get citations aggregates](/api/topic/performance/get-citations-aggregates): Retrieve a paginated list of topic citations aggregates. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/citations/aggregates` with the `promptType` query parameter for a Branded/Non-Branded split, or create a View (`POST /api/v1/brands/{brand}/views`) to replicate this topic's specific prompt grouping and query `GET /api/v1/views/{view}/citations/aggregates` instead.
      - [Get citations time series](/api/topic/performance/get-citations-time-series): Retrieve topic time series data showing citations evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/citations/timeseries` with the `promptType` query parameter for a Branded/Non-Branded split, or create a View (`POST /api/v1/brands/{brand}/views`) to replicate this topic's specific prompt grouping and query `GET /api/v1/views/{view}/citations/timeseries` instead.
      - [Get sentiment aggregates](/api/topic/performance/get-sentiment-aggregates): Retrieve a flat, paginated list of sentiment aggregates for a topic. Each row represents a unique brand-feature pair with counts of endorsed, undermined, and neutral feature mentions. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/sentiment/aggregates` with the `promptType` query parameter for a Branded/Non-Branded split, or create a View (`POST /api/v1/brands/{brand}/views`) to replicate this topic's specific prompt grouping and query `GET /api/v1/views/{view}/sentiment/aggregates` instead.
      - [Get sentiment time series](/api/topic/performance/get-sentiment-time-series): Retrieve daily sentiment distribution over time for the owned brand within a topic (competitors are not included). Returns counts of endorsed, undermined, and neutral feature mentions per day within the specified date range. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/sentiment/timeseries` with the `promptType` query parameter for a Branded/Non-Branded split, or create a View (`POST /api/v1/brands/{brand}/views`) to replicate this topic's specific prompt grouping and query `GET /api/v1/views/{view}/sentiment/timeseries` instead.
      - [Get share of voice aggregates](/api/topic/performance/get-share-of-voice-aggregates): Retrieve a paginated list of topic share of voice aggregates. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/share-of-voice/aggregates` with the `promptType` query parameter for a Branded/Non-Branded split, or create a View (`POST /api/v1/brands/{brand}/views`) to replicate this topic's specific prompt grouping and query `GET /api/v1/views/{view}/share-of-voice/aggregates` instead.
      - [Get share of voice time series](/api/topic/performance/get-share-of-voice-time-series): Retrieve topic time series data showing share of voice evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/share-of-voice/timeseries` with the `promptType` query parameter for a Branded/Non-Branded split, or create a View (`POST /api/v1/brands/{brand}/views`) to replicate this topic's specific prompt grouping and query `GET /api/v1/views/{view}/share-of-voice/timeseries` instead.
      - [Get visibility aggregates](/api/topic/performance/get-visibility-aggregates): Retrieve a paginated list of topic visibility aggregates. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/visibility/aggregates` with the `promptType` query parameter for a Branded/Non-Branded split, or create a View (`POST /api/v1/brands/{brand}/views`) to replicate this topic's specific prompt grouping and query `GET /api/v1/views/{view}/visibility/aggregates` instead.
      - [Get visibility time series](/api/topic/performance/get-visibility-time-series): Retrieve topic time series data showing visibility evolution over time for a brand and its competitors. Returns data points for each brand within the specified date range. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `GET /api/v1/brands/{brand}/visibility/timeseries` with the `promptType` query parameter for a Branded/Non-Branded split, or create a View (`POST /api/v1/brands/{brand}/views`) to replicate this topic's specific prompt grouping and query `GET /api/v1/views/{view}/visibility/timeseries` instead.
  - Trend
    - [Accept trend](/api/trend/accept-trend): Accepts a trend and starts monitoring all the selected prompt ids. This converts the trend into an active topic that can be managed via the topics endpoints. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `POST /api/v1/brands/{brand}/prompts` to create and start monitoring prompts directly instead.
    - [Import trends](/api/trend/import-trends): Creates new trends from a list of imported keywords. This method is asynchronous and it requires querying for new trends to see when the import finishes. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation — if so, use `POST /api/v1/brands/{brand}/prompts` to create prompts directly instead.
    - [List trends](/api/trend/list-trends): Retrieve a paginated list of trends. **Deprecated**: Returns a `410 Gone` error once Topics are disabled for your account due to deprecation. No direct replacement — use `GET /api/v1/brands/{brand}/prompts` to list all prompts for a brand instead. It supports `type`, `countries`, and `tags` filters to narrow the results.
  - View
    - [Create view](/api/view/create-view): Create a view for a brand. The view name must be unique per brand (case-insensitive). Omit `filters` (or pass `{}`) for a view matching all of the brand's prompts. A view is a named saved filter over a brand's prompts (any combination of prompt type, countries, tags, and status). The prompt set is resolved from the filters at query time, so a view always reflects the brand's current prompts.
    - [Delete view](/api/view/delete-view): Delete a view. Only the saved filter is removed — the prompts it groups are not affected.
    - [Get view](/api/view/get-view): Retrieve a view by its id. A view is a named saved filter over a brand's prompts (any combination of prompt type, countries, tags, and status). The prompt set is resolved from the filters at query time, so a view always reflects the brand's current prompts.
    - [List view prompts](/api/view/list-view-prompts): Retrieve the paginated list of prompts the view currently groups, with summary performance metrics per prompt. The prompt set is resolved from the view's saved filters at query time.
    - [List views](/api/view/list-views): Retrieve a paginated list of the brand's views. A view is a named saved filter over a brand's prompts (any combination of prompt type, countries, tags, and status). The prompt set is resolved from the filters at query time, so a view always reflects the brand's current prompts.
    - [Update view](/api/view/update-view): Update a view's name and/or filters. `filters` replaces the entire filters object — include every criterion the view should keep.
    - Performance
      - [Get citation aggregates](/api/view/performance/get-citation-aggregates): Retrieve a paginated list of citation aggregates over the prompts the view groups. The prompt set comes from the view's saved filters; the query parameters only control dates, engine, sorting, filtering by source, and pagination.
      - [Get citations time series](/api/view/performance/get-citations-time-series): Retrieve citations time series over the prompts the view groups. The prompt set comes from the view's saved filters; the query parameters only control dates and engine.
      - [Get sentiment aggregates](/api/view/performance/get-sentiment-aggregates): Retrieve a paginated list of sentiment aggregates (one row per brand-feature pair) over the prompts the view groups. The prompt set comes from the view's saved filters; the query parameters only control dates, engine, sorting, filtering by brand or feature, and pagination.
      - [Get sentiment time series](/api/view/performance/get-sentiment-time-series): Retrieve daily sentiment feature mention distribution over the prompts the view groups. The prompt set comes from the view's saved filters; the query parameters only control dates and engine.
      - [Get share of voice aggregates](/api/view/performance/get-share-of-voice-aggregates): Retrieve a paginated list of share of voice aggregates over the prompts the view groups. The prompt set comes from the view's saved filters; the query parameters only control dates, engine, sorting, and pagination.
      - [Get share of voice time series](/api/view/performance/get-share-of-voice-time-series): Retrieve share of voice time series over the prompts the view groups. The prompt set comes from the view's saved filters; the query parameters only control dates and engine.
      - [Get visibility aggregates](/api/view/performance/get-visibility-aggregates): Retrieve a paginated list of visibility aggregates over the prompts the view groups. The prompt set comes from the view's saved filters; the query parameters only control dates, engine, sorting, and pagination.
      - [Get visibility time series](/api/view/performance/get-visibility-time-series): Retrieve visibility time series over the prompts the view groups. The prompt set comes from the view's saved filters; the query parameters only control dates and engine.
- MCP Server
  - [Overview](/mcp): The Omnia MCP Server connects AI assistants like Claude, Cursor, and ChatGPT directly to your brand's AI visibility data. Query share of voice, citations, and sentiment in natural language — no dashboards required.
  - [Connecting to Omnia MCP](/mcp/connecting): Step-by-step guide to connecting Claude, Cursor, ChatGPT, or any MCP-compatible AI assistant to the Omnia MCP Server. Authenticate with OAuth and start querying your AI visibility data instantly.