curl --request POST \
  --url https://app.surfacd.com/api/v1/projects/{project}/reports/{entity} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "compare_start_date": "2026-08-04",
  "compare_end_date": "2026-08-31",
  "dimensions": [
    "brand"
  ],
  "measures": [
    "visibility",
    "sentiment",
    "avg_position"
  ],
  "filters": [
    {
      "field": "brand",
      "op": "in",
      "values": [
        "4e1f77d6-35d8-4a29-9fb6-d83e51469b35"
      ]
    }
  ]
}
'

{
  "id": "visibility",
  "title": "Visibility",
  "description": "How brands appear in AI answers: totals per group, or one row per answer",
  "empty": "No visibility data for the selected filters",
  "tooltip": null,
  "label": null,
  "badge": null,
  "group": "Report",
  "value": 0.16157205,
  "column": {
    "id": "value",
    "title": "Visibility",
    "type": "measure",
    "format": "percent",
    "decimals": 1,
    "prefix": "",
    "suffix": ""
  },
  "from": "2026-09-01",
  "to": "2026-09-28",
  "columns": [
    {
      "id": "brand_uuid",
      "title": "Brand id",
      "type": "dimension",
      "format": "number",
      "decimals": null,
      "prefix": "",
      "suffix": ""
    },
    {
      "id": "brand",
      "title": "Brand",
      "type": "dimension",
      "format": "number",
      "decimals": null,
      "prefix": "",
      "suffix": ""
    },
    {
      "id": "visibility",
      "title": "Visibility",
      "type": "measure",
      "format": "percent",
      "decimals": 1,
      "prefix": "",
      "suffix": ""
    },
    {
      "id": "visibility_compare",
      "title": "Visibility (compare)",
      "type": "measure",
      "format": "percent",
      "decimals": 1,
      "prefix": "",
      "suffix": ""
    },
    {
      "id": "visibility_change",
      "title": "Visibility (change)",
      "type": "measure",
      "format": "percent",
      "decimals": 1,
      "prefix": "",
      "suffix": ""
    }
  ],
  "rows": [
    {
      "brand_uuid": "4e1f77d6-35d8-4a29-9fb6-d83e51469b35",
      "brand": "Apple",
      "visibility": 0.16157205,
      "visibility_compare": 0.16397849,
      "visibility_change": -0.0024064332
    }
  ],
  "page": {
    "offset": 0,
    "limit": 100,
    "total": 1
  },
  "related": {},
  "benchmarks": [
    {
      "name": "Compare period",
      "type": "compare",
      "from": "2026-08-04T00:00:00.000000Z",
      "to": "2026-08-31T00:00:00.000000Z",
      "value": 0.16397849,
      "rows": [],
      "difference": -0.00240644,
      "ratio": 0.99,
      "change": -0.01,
      "favourable": false,
      "aboveOrBelow": "below",
      "lowerIsBetter": false
    }
  ],
  "actions": []
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "errors": {}
}

Reports

Run a Report Query

Runs one report query against the project and returns a dataset.

The body says what to group by (dimensions), what to compute (measures) and what to keep (filters). Every app report can be rebuilt with this endpoint; the Reports API guide in the docs shows the body for each page and widget.

Rows are dimension groups. dimensions: ["brand"] is one row per brand, ["brand", "service"] one row per brand per platform, ["brand", "date"] a timeline. Omit dimensions for one project-level row. A brand with no mentions still gets a zero-filled row. On visibility, ["answer"] is one row per AI answer, a list.
Filters have roles. A population field (service, country, tag, topic, prompt, mentions_brand, cites_domain, mention_sentiment on sources, carries_narrative, carries_theme) narrows which AI answers are counted and so changes every number, including denominators; it takes in only. An entity field (brand, domain, narrative, …) or a measure field hides rows after the numbers are computed and never changes a number; entity fields need their dimension on the row.
Compare window. compare_start_date and compare_end_date run the same query over a second window and add <measure>_compare and <measure>_change columns, usable in filters and order_by. Time buckets pair by position from each window’s start. A single-row result also fills benchmarks[0] for a KPI card.
Paging. limit (default 100, max 1000) and offset; page.total is the row count before the page was cut. rank is assigned per group before any row filter, so rank lte 5 is “top five per group”.
Related blocks. related adds per-row lists such as brands_on_page (sources), brands_in_answer, sources_in_answer, answer_text (visibility with the answer dimension) and narrative_description, evidence (narratives). Each entry carries row, the index of its row.

GET /api/v1/reports/{entity}/schema lists what each entity accepts and GET /api/v1/projects/{project}/reports/values/{field} lists the identifiers a filter takes. The narratives entity and the carries_narrative / carries_theme filters need the Reputation capability.

POST

api

projects

{project}

reports

{entity}

curl --request POST \
  --url https://app.surfacd.com/api/v1/projects/{project}/reports/{entity} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "compare_start_date": "2026-08-04",
  "compare_end_date": "2026-08-31",
  "dimensions": [
    "brand"
  ],
  "measures": [
    "visibility",
    "sentiment",
    "avg_position"
  ],
  "filters": [
    {
      "field": "brand",
      "op": "in",
      "values": [
        "4e1f77d6-35d8-4a29-9fb6-d83e51469b35"
      ]
    }
  ]
}
'

{
  "id": "visibility",
  "title": "Visibility",
  "description": "How brands appear in AI answers: totals per group, or one row per answer",
  "empty": "No visibility data for the selected filters",
  "tooltip": null,
  "label": null,
  "badge": null,
  "group": "Report",
  "value": 0.16157205,
  "column": {
    "id": "value",
    "title": "Visibility",
    "type": "measure",
    "format": "percent",
    "decimals": 1,
    "prefix": "",
    "suffix": ""
  },
  "from": "2026-09-01",
  "to": "2026-09-28",
  "columns": [
    {
      "id": "brand_uuid",
      "title": "Brand id",
      "type": "dimension",
      "format": "number",
      "decimals": null,
      "prefix": "",
      "suffix": ""
    },
    {
      "id": "brand",
      "title": "Brand",
      "type": "dimension",
      "format": "number",
      "decimals": null,
      "prefix": "",
      "suffix": ""
    },
    {
      "id": "visibility",
      "title": "Visibility",
      "type": "measure",
      "format": "percent",
      "decimals": 1,
      "prefix": "",
      "suffix": ""
    },
    {
      "id": "visibility_compare",
      "title": "Visibility (compare)",
      "type": "measure",
      "format": "percent",
      "decimals": 1,
      "prefix": "",
      "suffix": ""
    },
    {
      "id": "visibility_change",
      "title": "Visibility (change)",
      "type": "measure",
      "format": "percent",
      "decimals": 1,
      "prefix": "",
      "suffix": ""
    }
  ],
  "rows": [
    {
      "brand_uuid": "4e1f77d6-35d8-4a29-9fb6-d83e51469b35",
      "brand": "Apple",
      "visibility": 0.16157205,
      "visibility_compare": 0.16397849,
      "visibility_change": -0.0024064332
    }
  ],
  "page": {
    "offset": 0,
    "limit": 100,
    "total": 1
  },
  "related": {},
  "benchmarks": [
    {
      "name": "Compare period",
      "type": "compare",
      "from": "2026-08-04T00:00:00.000000Z",
      "to": "2026-08-31T00:00:00.000000Z",
      "value": 0.16397849,
      "rows": [],
      "difference": -0.00240644,
      "ratio": 0.99,
      "change": -0.01,
      "favourable": false,
      "aboveOrBelow": "below",
      "lowerIsBetter": false
    }
  ],
  "actions": []
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "errors": {}
}

Authorizations

Authorization

string

header

required

Team API key created in Team Settings. Use it with URLs for the same team.

Path Parameters

project

string<uuid>

required

Project UUID.

entity

enum<string>

required

The report entity. A report entity. visibility: brand visibility, mentions, position, sentiment and rank; with the answer dimension, one row per AI answer (a list, no compare window). sources: cited domains, hostnames, URLs and pages. narratives: reputation narratives, themes and sentiment (needs the Reputation capability).

Available options:

visibility,

sources,

narratives

Body

application/json

A report query. Rows are dimension groups; measures are the numbers computed per group; filters narrow the population or hide rows. Omit dimensions for one project-level row.

start_date

string<date>

required

Inclusive start of the window.

end_date

string<date>

required

Inclusive end of the window, on or after start_date.

measures

string[]

required

The numbers to compute per row. The schema endpoint lists the entity's measures.

Minimum array length: 1

compare_start_date

string<date> | null

Optional second window to compare against. Required when compare_end_date is present. Every measure then gains <measure>_compare and <measure>_change columns. Not accepted with the answer dimension on visibility.

compare_end_date

string<date> | null

Required when compare_start_date is present; on or after it.

dimensions

string[]

What each row groups by, in display order. Use at most one time bucket (date, week or month). On visibility, answer makes one row per AI answer. The schema endpoint lists the entity's dimensions.

filters

object[]

Show child attributes

order_by

object[]

Defaults to the entity's own order (for example visibility descending on visibility, newest first with the answer dimension).

Show child attributes

limit

integer

default:100

Required range: 1 <= x <= 1000

offset

integer

default:0

Required range: x >= 0

Extra per-row blocks the entity offers, such as brands_on_page on sources, brands_in_answer, sources_in_answer and answer_text on visibility with the answer dimension, narrative_description and evidence on narratives. Each entry in the response names its row by index.

top

object

Keep only the best values of one dimension, ranked over the whole window, on every row. {"field": "brand", "by": "visibility", "limit": 6} on ["brand", "date"] gives the six most visible brands for every day, where limit would give six rows. Lower-is-better measures rank ascending. Not with the answer dimension.

Show child attributes

Response

The report dataset.

The result of a report query: a column schema, raw rows keyed by column id, paging, optional related blocks and, for a single-row compare query, a benchmark.

enum<string>

required

A report entity. visibility: brand visibility, mentions, position, sentiment and rank; with the answer dimension, one row per AI answer (a list, no compare window). sources: cited domains, hostnames, URLs and pages. narratives: reputation narratives, themes and sentiment (needs the Reputation capability).

Available options:

visibility,

sources,

narratives

title

string

required

columns

object[]

required

The row schema in display order: id columns (brand_uuid, prompt_uuid, ...), dimensions, then each measure followed by its _compare and _change columns when a compare window is set.

Show child attributes

rows

object[]

required

One object per row, keyed by column id. Percent measures are decimals; a null compare column means the compare window had no matching row.

page

object

required

Show child attributes

One list per requested block, keyed by block id.

Show child attributes

benchmarks

object[]

required

Show child attributes

description

string

empty

string

Text to show when rows is empty.

label

string | null

badge

string | null

group

string

value

number

Headline value of the first measure when the result has exactly one row, otherwise 0.

column

object

How to format one column of rows. format: percent values are decimals (0.42 means 42%).

Show child attributes

from

string<date>

actions

object[]

Reference

Projects

Prompts

Reporting

Tags

Reputation

Team

Reports

Run a Report Query

Authorizations

Path Parameters

Body

Response