Skip to main content
API and MCP access is included on all plans. Browse the API Reference for the full endpoint contract.
The Reports API is one endpoint per report entity. You send a small JSON body that says what to group by, what to compute, what to count and which rows to return. You get back rows plus a column schema, so the same response renders in a spreadsheet, a BI tool, a script or an AI assistant. Every report page and widget in Surfacd can be rebuilt with it. The entity pages show the exact body for each one:

Visibility

Visibility, mentions, position, sentiment and rank, or one row per AI answer. Dashboard, Rankings, Analyse, Prompts and Brand Mentions.

Sources

Cited domains, hostnames, URLs and pages. Sources overview, tables, gaps and page sentiment.

Narratives

Reputation narratives, themes and sentiment. Requires the Reputation feature.

Queries

The web searches AI platforms ran while answering your prompts: per prompt, per platform, over time.

Endpoints

All three use a team API key as a Bearer token. {project} is the project UUID from GET /api/v1/projects.

Your first query

Visibility per brand over the last four weeks, best first:
columns tells you how to format each cell. rows are raw values keyed by column id. A percent column is a decimal: 0.203 is 20.3%.

The request

Rows and dimensions

A row is one dimension group.
  • "dimensions": ["brand"] is one row per brand.
  • "dimensions": ["brand", "service"] is one row per brand per platform.
  • "dimensions": ["brand", "date"] is a timeline, one row per brand per day. week and month bucket the same way. Use one time bucket per query.
  • "dimensions": ["service"] on visibility, without brand, aggregates across the project’s brands: one row per platform.
  • No dimensions at all gives one project-level row, which is what a KPI card needs.
A brand with no mentions in the window still gets a row, zero-filled, so rankings and charts stay complete. Every dimension with a name also carries a key column: brand comes with brand_uuid, prompt with prompt_uuid, topic with topic_uuid, service with service_provider (the platform slug, google_ai_mode beside “Google AI Mode”), country with country_code (the ISO code, US beside “United States”), and so on. Each of these columns is also a field of the same name in scope and filters, so any value in a row can go straight back into a condition: a row’s brand_uuid goes in a brand_uuid condition, its topic name in a topic condition. Prompts without a topic form one group whose topic and topic_uuid are null.

Scope and filters

A query has two lists of conditions. Both hold the same { "field", "op", "values" } or { "field", "op", "value" } conditions. They differ in what they are allowed to change:
  • scope decides what is counted and ranked. Which AI answers count, which brand the page or answer columns describe, which cited pages count, and which rows take part in rank, top and the compare window. Anything that changes a number goes here.
  • filters decides which result rows come back. It never changes a number, rank included.
The list you put a condition in says what it does. The field’s operator never changes that. A field that only makes sense in one list is a 422 in the other, and the message says which list it belongs in.
  • “ChatGPT only” goes in scope. { "field": "service_provider", "op": "in", "values": ["chatgpt"] } in scope makes visibility = mentions on ChatGPT ÷ answers on ChatGPT, the same as the platform filter in the app.
  • “Just my brand” goes in filters. { "field": "brand_uuid", "op": "in", "values": ["YOUR_BRAND_UUID"] } in filters keeps one row and drops the rest. Your visibility and rank are exactly what they are with no filter.
In either list, the values of one condition are alternatives and separate conditions all apply. { "field": "service_provider", "op": "in", "values": ["chatgpt", "gemini"] } counts the answers on either platform, and a platform condition beside a country condition in scope counts the answers on that platform in that country. Repeated conditions on row fields, on page fields and in filters each narrow further. Two scope conditions on the same answer cut also both apply, and what that means depends on the cut:
  • One value per answer: platform (service_provider, service), country (country_code, country), topic (topic_uuid, topic), prompt (prompt_uuid, prompt), branded and mention_sentiment. Repeated conditions keep the values they share, whether they use the key field or the name field: { "field": "service_provider", "op": "in", "values": ["chatgpt", "claude"] } beside { "field": "service", "op": "contains", "value": "claude" } keeps Claude’s answers. When they share no value, no answer counts and the report is empty.
  • Several values per answer: tags (tag_uuid and tag are one cut), mentions_brand, cites_domain, carries_narrative, carries_theme, carries_sentiment and search_query. An answer can name several brands, cite several domains or come from a prompt with several tags, so keeping the values two lists share would not mean “both”. A second in or contains condition on one of these cuts is a 422: put the values in one condition. in keeps the answers matching any of them, and for tags { "field": "tag_uuid", "op": "all", "values": [...] } keeps the prompts that carry every one.
  • not_in on mentions_brand and all on tag_uuid may repeat, beside one in: { "field": "mentions_brand", "op": "not_in", "values": ["YOUR_BRAND_UUID"] } with { "field": "mentions_brand", "op": "in", "values": ["competitors"] } counts the answers that name a competitor and not you.

Rank against your competitors, return only your row

The scope ranks your brand and the brands you marked as competitors (competitors is a reserved value, see Your marked competitors) against each other. The filter then returns your row alone. rank is your place against your competitors, from 1. visibility is still your share of every answer, as it is without either condition: a brand condition in scope chooses who is ranked, not which answers are counted. The same brand list in different places:

What scope narrows

Measures, their _compare and _change columns, compare bands such as momentum, and the is_null / not_null checks describe result rows, so they go in filters; in scope they are a 422.

What filters pick

The answer conditions that are not row columns (branded, mentions_brand, cites_domain, carries_narrative, carries_theme, carries_sentiment, search_query, and mention_sentiment outside visibility), the lenses, competitors_on_page, and a sources page field whose dimension is not on the row change what is counted, so they go in scope; in filters they are a 422. A dimension column in filters without its dimension in dimensions would cut the answers instead of picking rows, so it is a 422 that says to put it in scope or add the dimension. Filters run before paging, so page.total counts the rows they keep.

Key fields and name fields

A field matches the row column of the same name. Every field that has both an id and a name comes as two fields:
  • A key field matches ids exactly, with in and not_in. In scope, the answer fields take in only, and tag_uuid also takes all.
  • A name field matches what the row shows: in and not_in by whole name, ignoring letter case, so { "field": "topic", "op": "in", "values": ["running"] } matches the topic “Running”. This holds in both lists and in the checks below. contains searches the name: it takes a text value and matches case-insensitively and literally: % and _ match themselves, and spaces around the words are ignored. In scope, the answer fields take in and contains. The platform name is the one the service column shows, such as “Google AI Mode”.
  • in and not_in values are checked, in both lists. An id or a name the project does not have is a 422 that names the value and says what the field matches, so { "field": "topic", "op": "in", "values": ["<a topic uuid>"] } tells you to use topic_uuid. Country codes and names are checked against every country Surfacd knows, not only the project’s. In scope, the other answer cuts are checked too: mentions_brand against the project’s brands, carries_narrative and carries_theme against its narratives and themes, cites_domain against the domains AI answers have cited (in any letter case, spaces around them ignored), and mention_sentiment and carries_sentiment against positive, negative and neutral. An unknown one is a 422 at scope.N.values. contains is never checked: a search that matches nothing returns nothing.
  • A name in scope selects every record with that name, in any letter case, and contains every record whose name contains the text: { "field": "prompt", "op": "contains", "value": "running shoes" } in scope counts the answers to every prompt that mentions running shoes. When a scope search matches no record, nothing is counted; it never falls back to every answer.
  • no_topic and untagged select the answers to prompts without a topic or without tags, so they are scope values of topic_uuid and tag_uuid. In filters they are a 422: there, { "field": "topic_uuid", "op": "is_null" } keeps the row of prompts without a topic.
  • Key fields are not sort fields. Sort by the dimension: order_by brand, not brand_uuid.
Fields with one column keep one name: domain, hostname, url, category, page_type, page_sentiment, brand_on_page, query, mention_sentiment, narrative_sentiment, search, answer_search. So do the fields that are not row columns: branded, mentions_brand, cites_domain, carries_narrative, carries_theme, carries_sentiment, search_query, the lenses answer_brand and page_brand, and competitors_on_page.

Searching rows by name

contains on a name field searches the names the rows show. On visibility and narratives, where you put it decides what it does:
  • In filters, { "field": "topic", "op": "contains", "value": "pricing" } with topic in dimensions keeps the topic rows whose name contains “pricing”. Every number, rank included, stays as it was, and the row count and pages follow the search. The group of prompts without a topic has no name, so contains never matches it, and not_in on topic drops it too.
  • In scope, the same condition counts only the answers to prompts in those topics, so every number becomes a number about those topics. It needs no dimension.

Answer field values

No service_provider or service condition means the project’s active platforms, the same default as the rest of the API. tag_uuid in [...] keeps prompts with any of the listed tags. To keep only prompts that carry every listed tag, use the all operator, which also takes values. It applies to every entity and both comparison windows. untagged selects prompts without tags with in, on its own or beside real tags; it cannot be used with all. Prompt branding remains a separate branded condition. untagged is a reserved value of tag_uuid; a real tag named “untagged” is selected by name with tag.
This keeps prompts with both tags. The content cuts, mentions_brand, cites_domain and mention_sentiment, make “answers that name us” or “answers that cite Reddit” the whole population. Every ratio is then a share of those answers. Add the answers measure to see the denominator.

Null checks

is_null and not_null take neither value nor values and go in filters. They accept measure fields, and the row fields and dimension columns of the dimensions in dimensions. They hide result rows, so the remaining rows keep their metrics, ranks and comparison values, and they run before paging, so the row count reflects the filtered result. For example, request topic in dimensions and add { "field": "topic", "op": "not_null" } to filters to omit the group for prompts without a topic. Named historical topics remain included. This does not exclude unassigned prompts from unrelated reports. Measure null checks distinguish a missing observation from a measured zero. Comparison fields still require a comparison window: { "field": "citations_compare", "op": "is_null" } keeps rows with no matching observation in that window.

Your marked competitors

Brand lists accept competitors, a reserved value for the brands you marked as competitors in the project. It works in brand_uuid (rows on visibility and narratives, or the sources page comparison set) and in mentions_brand (in and not_in) on every entity, on its own or beside brand UUIDs. You don’t need to look up or send their UUIDs, and the list stays current when you mark or unmark a competitor. On visibility and narratives, where you put it decides what it does:
  • In scope, { "field": "brand_uuid", "op": "in", "values": ["YOUR_BRAND_UUID", "competitors"] } ranks those brands against each other. rank, rank_compare and top see only them, so ranks run from 1 among them. not_in with competitors ranks the brands that are left.
  • In filters, { "field": "brand_uuid", "op": "in", "values": ["competitors"] } returns the competitors’ rows with their rank among every brand.
  • { "field": "mentions_brand", "op": "in", "values": ["competitors"] } in scope counts the answers that name at least one of them; not_in counts the answers that name none.
A listed brand that no answer names has a null rank and takes no place. With no competitors marked, competitors matches no brand: the rows or answers it selects are empty rather than falling back to every brand. On Sources, brand_uuid is scope-only and selects the page comparison set with no brand dimension; it does not select answer mentions. See Sources comparison brands. Each schema lists the fields that take it under competitor_fields. The page-brand and answer-brand lenses name a single brand, so they don’t accept it, and neither does a mentions_brand condition paired with mention_sentiment. Use a brand’s UUID there.

Compare window

compare_start_date and compare_end_date run the same query over a second window. Same scope and filters, other dates. Every measure then gains two columns, right after it:
  • Both work in filters and order_by. “Movers” is order_by: [{ "field": "share_change", "dir": "desc" }]. “Dropped 10 points” is { "field": "visibility_change", "op": "lte", "value": -0.1 } in filters.
  • On narratives, share also gains momentum, the band the Reputation pages give its move (emerging, surging, steady, cooling, dormant). Filter on it with in / not_in. See Narratives.
  • Rows match on their dimension keys. A date, week or month row matches by position from each window’s start: day 1 pairs with day 1, so a 28-day chart overlays the previous 28 days. A day with no answers leaves a hole and does not shift the days after it. Windows of different lengths pair from the start; the longer tail reads null.
  • A single-row result also fills benchmarks[0] with value, difference, change and favourable for the first measure, so a KPI card can show its trend. avg_position counts down as good.
  • Ratios compare fairly across unequal windows. Counts do not: 186 mentions over 28 days against 71 over 14 is not a trend.
  • meta.answers_compare says whether the compare window had any answers at all. When it is 0, every _compare value is empty because there was nothing to measure, not because something was lost or is new.
  • Visibility with the answer dimension is a list and takes no compare window.

Rows that exist in only one window

A row is one set of dimension values: Alpha on Claude, reddit.com, one narrative. Some rows only have data in one of the two windows. A platform you started tracking this month has nothing last month, and a domain that stopped being cited has nothing this month. By default the report returns the rows the current window has, so a row that only the compare window has is left out. That suits most reports: a table of this month’s domains with their change since last month. It doesn’t suit reports about what was lost, such as “domains we stopped being cited on”, or a breakdown that has to add up to last month’s total. compare_rows chooses which rows come back: On a row that only the compare window has, the current measures are empty: counts (mentions, answers, citations and the like) are 0, and every other measure (visibility, share, sentiment, avg_position, rank and the like) is null, because it has no value without data. The _compare columns hold the compare window’s values. _change is current minus compare: a count shows the full loss, such as -2, and any other measure reads null. Filters and order_by read the same values, so { "field": "citations", "op": "eq", "value": 0 } with compare_rows: "previous" lists exactly what was lost. previous and any need a compare window, and can’t be used with a date, week or month dimension: time rows pair by their position in each window, so a day only the compare window has has no date in the current one.
This lists the domains cited last month and not at all this month, the most-cited first.

Paging and rank

  • limit and offset cut the rows. page.total in the response is the row count before the cut, so you can build a pager. It is correct even on a page past the end.
  • The rank measure numbers rows within their group by the entity’s main measure: visibility on visibility, citations on sources, runs on fan-out queries. It is assigned among the rows the scope keeps, before any filter, so { "field": "rank", "op": "lte", "value": 3 } in filters on ["brand", "service"] is “the top three brands on each platform” and does not renumber anyone. To rank a set of rows against each other, such as you and your competitors, put the set in scope (see Rank against your competitors). Ties never share a place: each entity breaks them in a fixed order, so ranks run 1, 2, 3. A row with nothing to rank has null: a brand not named in its group, a narrative no answer carries, a prompt that ran no search.
  • top keeps the best values of one dimension over the whole window, on every row. "top": { "field": "brand", "by": "visibility", "limit": 6 } on ["brand", "date"] gives the six most visible brands for every day, where limit: 6 would give six rows. The field must be in dimensions and cannot be date, week or month. Measures where lower is better, such as avg_position, rank ascending. It hides rows and never changes a number.
  • top picks among the values the scope keeps, and a condition in filters on the top field or on another dimension in the row narrows the candidates too. A brand_uuid list of five competitors with a top brand of 3 gives the best three of those five. A brand_uuid filter on your brand with "top": { "field": "service", "by": "visibility", "limit": 3 } gives the three platforms where your brand is most visible (with several brands, each platform goes by its best brand). Measure filters still apply row by row afterwards. A tie goes the way rank orders the values, and by need not be one of measures.
  • contains on a row field in filters is your search box: { "field": "url", "op": "contains", "value": "reddit" }.
Some entities offer extra per-row lists that would not fit a flat row: the brands named on a cited page, the sources an answer cites, a narrative’s evidence. Ask for them in related; they come back under related in the response, one list per block. Each entry carries row, the index of its row in rows, so filtering or sorting rows on your side never loses the link.

The response

Finding identifiers

Scope and filter conditions take public identifiers only: UUIDs, slugs, codes and names. Two endpoints tell you what to send. The schema endpoint lists what an entity accepts. scope_fields and filter_fields list every field each list takes. Each entry has the field’s role (population, lens, page, entity, measure or compare), the operators it takes in that list, and dimension: the dimension that must be in dimensions for the field to be used there, or null. competitor_fields names the brand lists that take competitors. combined_brand_fields names the scope brand lists that combine brands when their dimension is left out (brand_uuid on Visibility, empty elsewhere): with brand in dimensions the list picks rows, without it the listed brands are added together into one row per group. See One row per brand, or the brands combined.
The same field can have a different role in each list. page_type is a page field in scope, where it narrows the cited pages, and an entity field in filters, where it picks page_type rows. service_provider cuts the answers in scope and picks service rows in filters. order_fields lists what order_by takes. The values endpoint lists what a field takes for your project, with a search:
Put value in the condition. label and description are for people: the primary brand is marked, domains carry their citation count, narratives their sentiment and theme. A key field lists its keys with their names as labels, so values/service_provider gives { "value": "google_ai_mode", "label": "Google AI Mode" } and you never map codes to names yourself; a name field lists the names. brand_uuid and mentions_brand list competitors first, tag_uuid lists untagged first and topic_uuid lists no_topic first. A name field lists each name once, with the name as both value and label, and no reserved values. Fields with a list: brand_uuid, brand, mentions_brand, page_brand, answer_brand, narrative_uuid, narrative, carries_narrative, theme_uuid, theme, carries_theme, prompt_uuid, prompt, topic_uuid, topic, tag_uuid, tag, branded, service_provider, service, country_code, country, domain, cites_domain, page_type, category, brand_on_page, mention_sentiment, page_sentiment, narrative_sentiment, carries_sentiment.

Errors

Validation problems return 422 with errors keyed by the offending path: scope.0.field, filters.1.values and so on, so a wrong body tells you where. 403 means the query reads reputation data (the narratives entity, or a carries_narrative, carries_theme or carries_sentiment condition) and the team does not have the Reputation feature. 404 means the project is not in the key’s team.

Moving from a single filters list

Before scope, every condition went in filters and the field decided where it ran. Bodies written that way need these changes: Measures, compare bands, null checks and the single-column row fields (domain, url, query and the like) stay in filters.

Deprecated endpoints

The Reports API replaces these single-report endpoints. They keep working until a removal date is announced. New integrations should use the report query. All paths start with /api/v1. The detail endpoints (one theme, narrative or response by UUID) and mentions are not deprecated.

Using it from an AI assistant

The MCP server exposes the same capability as tools: run_report runs a query, get_report_schema and list_report_values describe what it accepts, and get_report_query_guide explains how to write one. An assistant connected to Surfacd can build any of the reports on the entity pages on request. Put search_query in [text] in scope on any report entity to count only answers that ran an exact web search. Text matches case-insensitively, using the same query keys as the Queries report. Suggested follow-up questions and matching words in prompt or answer text do not count. Duplicate stored searches do not duplicate answers. Supply several query strings to include answers that ran any of them. On the Queries report, search_query selects the answers; it keeps all searches those answers ran. Add a query condition to filters to restrict the query rows as well.