---
title: "Get Links Report"
method: POST
path: "/reports/links"
tags: ["Reports"]
---

# Get Links Report

`POST /reports/links`

## Request

- Base URL: `https://api.peec.ai/customer/v1`
- URL: `https://api.peec.ai/customer/v1/reports/links`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in query parameter `api_key`
  - HTTP bearer

Get a report on the domains AI answers linked to in their own text. A link is a URL the answer wrote into its prose; it is never one of the sources the answer retrieved or cited, which the domains report covers.

## Prompt Scope

The report covers every prompt in the project that has not been deleted, archived prompts included, so history stays intact after a prompt is archived. Use a `prompt_id` filter to narrow it.

## Aggregation Formulas

When aggregating results across multiple rows/dimensions:

- **linked_percentage**: `sum(linked_chat_count) / sum(total_chat_count)`, only across rows that do not split the same chats (not across `url` rows of one domain).
- **average_link_position** is not additive across rows. Request the coarser breakdown instead.

## Query parameters

- `project_id` string: Required if using a company api key

## Request body

- object
  - `project_id` string: Required if using a company api key
  - `limit` integer
  - `offset` integer
  - `start_date` string, date: full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21
  - `end_date` string, date: full-date notation as defined by RFC 3339, section 5.6, for example, 2017-07-21
  - `dimensions` string[]: Dimensions to break down the report by. `url` breaks each linked domain down into the pages linked.
  - `filters` union[]: Row filters applied before aggregation. Allowed fields: `model_id` (deprecated), `model_channel_id`, `country_code`, `prompt_id`, `tag_id`, `topic_id`, `chat_id`, `domain`, `url`. Population fields (model/country/prompt/tag/topic/chat) shrink both the linked chats and `total_chat_count`; `domain` and `url` narrow the linked chats only. Multiple filters are AND'd.
    - union
      - object: Deprecated: use model_channel_id filter instead
        - `field` 'model_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'model_channel_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'tag_id', required
        - `operator` 'in' | 'not_in' | 'has_all', required
        - `values` string[], required
      - object
        - `field` 'topic_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'prompt_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'country_code', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'chat_id', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'domain', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
      - object
        - `field` 'url', required
        - `operator` 'in' | 'not_in', required
        - `values` string[], required
  - `order_by` object[]: Sort results by one or more fields. Multiple entries create a multi-key sort. Direction defaults to desc. When omitted, a default ordering is applied.
    - `field` 'linked_chat_count' | 'link_count' | 'average_link_position' | 'date' | 'week' | 'month', required
    - `direction` 'asc' | 'desc'

## Response `200`

Success

- object: Success
  - `data` object[], required
    - `domain` string, required
    - `url` string: The linked page, when the `url` dimension is set.
    - `classification` string, required: OWN, COMPETITOR or RELATED when the domain belongs to a tracked brand, the name of a custom domain classification, or OTHER.
    - `prompt` object
      - `id` string, required
    - `model` object: Deprecated: use model_channel instead
      - `id` string, required
    - `model_channel` object
      - `id` string, required
    - `tag` object
      - `id` string, required
    - `topic` object
      - `id` string, required
    - `country_code` string
    - `chat` object
      - `id` string, required
    - `date` string
    - `week` string: Start (Monday) of the ISO week bucket.
    - `month` string: First day of the month bucket.
    - `linked_chat_count` number, required: Number of distinct chats whose answer linked to this domain in its own text.
    - `linked_percentage` number, required: `linked_chat_count / total_chat_count`, from 0 to 1.
    - `link_count` number, required: Total number of links to this domain across those chats. An answer can link to the same page more than once.
    - `average_link_position` number, required: Average rank of this domain's links among each answer's links, where 1 is the first link in the answer.
    - `total_chat_count` number, required: Total number of chats in scope for this row, the denominator for `linked_percentage`. Population filters shrink it; `domain` and `url` filters do not.

## Changes

- **2026-11-03** `9d774600c8eb`: 3 breaking, 3 info
  - removed `subschema #1, subschema #2` from the `filters/items/` request property `anyOf` list (media type: application/json)
  - removed `subschema #1, subschema #2` from the `filters/items/` request property `anyOf` list (media type: application/x-www-form-urlencoded)
  - removed `subschema #1, subschema #2` from the `filters/items/` request property `anyOf` list (media type: multipart/form-data)
  - added `subschema #1, subschema #2` to the `filters/items/` request property `anyOf` list (media type: application/json)
  - …2 more
- **2026-11-03** `9fdffdff48a5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/peec/apis/peec-ai-customer-api/changes/reports/links/post.md)

---

[API](https://skmtc.dev/peec/apis/peec-ai-customer-api.md) - [All operations](https://skmtc.dev/peec/apis/peec-ai-customer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/peec/apis/peec-ai-customer-api/revisions/9d774600c8eb?raw)