Read tools

Inputs, outputs and examples for list_brands, list_questions, get_visibility_summary and get_run_status.

All read tools need a read (or write) credential, are annotated readOnlyHint=true, never start a measurement and never spend provider quota. Example values are illustrative.

`list_brands`

Lists the brands (projects) the key can read, ordered by id.

Argument	Type	Default	Notes
`limit`	integer 1–100	50	Page size.
`cursor`	string	none	`next_cursor` from the previous page.

Call

{ "limit": 2 }

Result

{
  "brands": [
    { "id": 12, "name": "Acme", "domain": "acme.com" },
    { "id": 15, "name": "Globex", "domain": "globex.example" }
  ],
  "next_cursor": "eyJ..."
}

`list_questions`

Lists the tracked questions of one brand, newest first.

Argument	Type	Default	Notes
`brand_id`	integer	required	From `list_brands`.
`status`	`active`, `paused` or `archived`	all	Filter.
`limit`, `cursor`			As above.

Result

{
  "questions": [
    {
      "id": 7,
      "brand_id": 12,
      "title": null,
      "content": "Best CRM for startups?",
      "language": "en",
      "target_country": "US",
      "category": null,
      "journey_stage": "consideration",
      "status": "active",
      "cadence": "daily",
      "providers": ["openai"]
    }
  ],
  "next_cursor": null
}

language and target_country are the question's research language and market, not your interface language. See Metrics and methodology.

`get_visibility_summary`

Returns the brand's report summary for a trailing UTC window.

Argument	Type	Default	Notes
`brand_id`	integer	required
`days`	integer 1–365	30	Window length.

The result is { "brand_id", "days", "summary" }. summary contains:

window: UTC start and end, plus the prior comparison window.
provider_coverage: every provider with its integration status and whether it was measured in the window.
data_sufficiency: attempted, successful, failed and pending responses; no_data, sparse or sufficient.
metrics: total_citations_extracted, brand_citations, unique_cited_domains, citation_share, citation_share_available, brand_citation_rate, and the two trend objects.
denominators: the scope behind citation_share and brand_citation_rate.
metric_definitions and measurement_basis: the definitions and the API-model caveat.

Result (abridged)

{
  "brand_id": 12,
  "days": 30,
  "summary": {
    "metrics": { "citation_share": null, "citation_share_available": false, "brand_citation_rate": 40.0 },
    "denominators": { "brand_citation_rate": { "successful_responses": 25 } }
  }
}

Percentages are on a 0–100 scale. A null percentage means there is not enough data to compute one; it is never reported as zero. Read Metrics and methodology before comparing citation_share with brand_citation_rate: their denominators differ.

`get_run_status`

Returns the status and response counts of a measurement run.

Argument	Type	Default	Notes
`brand_id`	integer	required
`run_id`	integer	latest run	Use the `run_id` returned by `trigger_run`.

Result

{
  "id": 57,
  "brand_id": 12,
  "status": "completed",
  "run_date": "2026-10-01T00:00:00",
  "completed_at": "2026-10-01T00:04:12",
  "responses_completed": 5,
  "responses_failed": 1,
  "responses_pending": 0
}

status takes values such as pending, completed, completed_with_errors and failed. A brand with no runs yet returns the error "This brand has no measurement runs yet."

list_brands

list_questions

get_visibility_summary

get_run_status

On this page

`list_brands`

`list_questions`

`get_visibility_summary`

`get_run_status`