Skip to Content
APIEndpointsNarrative

Brand Alignment: narrative

GET /v1/brands/:brand_id/alignment/narrative

Access is limited to the brands permitted by your credential. Requires read:alignment. Workspace API keys and signed-in MCP sessions are supported.

The entries in your brand narrative, what AI Should Say about you or Should Not Say, and how the answers describing your brand read them in one scan. This is the Narrative list in the “How AI positions you” card on the Brand Alignment page, and each entry’s detail view.

Asky manages the monitoring questions. Responses include results without exposing generated question text.

Query parameters

ParameterTypeDescription
scan_iduuidFinished scan identifier from the program endpoint. Defaults to the latest finished scan.
modelsstring (repeatable)Engine identifiers. Repeat this parameter to select multiple engines.
marketsstring (repeatable)Country codes (DE) or one country and language (DE:de-DE). Repeat this parameter to select multiple markets.
position_iduuidOne entry, by its id in this response: adds its share per scan and its answers.
verdictstringWith position_id: only answers with this reading, one of says, partly, counter or absent.
by_enginebooleanAlso each entry’s figures per engine.
answers_limitintegerWith position_id: answers to return, from 1 to 50. Defaults to 20.
answers_offsetintegerWith position_id: answers to skip.

Response

The standard API envelope places the result in data, with request_id beside it at the top level.

FieldDescription
brand_idThe brand these entries belong to.
slotsused and limit: how many entries the brand tracks now and the most it can track.
scanThe scan read: id, cutoff and state. Null before the first scan has finished.
positionsThe entries this scan read, Should Say first.
positions[].idIdentifies this entry’s wording. Rewording a entry gives it a new id and starts its trend again.
positions[].statementThe entry as the scan read it.
positions[].directionknown for Should Say, avoid for Should Not Say.
positions[].shareHow often answers say the entry. value is in percent, counting a partial mention as half, null when no answer was read. says, partly, counter (says otherwise) and absent (not mentioned) count the answers read.
positions[].previous_shareThe share in the previous scan that read the same wording. Null when there is none.
positions[].change_pointsThe change in percentage points since that scan. Null without one.
positions[].trendWhat the change means for your brand. gaining or losing for a Should Say entry, spreading or fading for a Should Not Say one, steady when the change is too small to call. Null with nothing to compare.
positions[].trend_tonegood, bad or neutral. A Should Not Say entry that is spreading is bad.
positions[].by_engineWith by_engine: the share fields per engine.
also_noticedOther ways the answers in this scan describe your brand that you do not track, with the same fields.
from_next_scanEntries saved since this scan’s list was set, measured from the next scan: id, statement and direction.
positionWith position_id.
position.historyThe entry’s share per scan, oldest first, for the scans that read this wording. Up to 26 scans.
position.answersThe answers behind it, from the reading that works most against the entry: counter, partly, then says for a Should Say entry; says, partly, then counter for a Should Not Say one; absent last, and the newest first within each. Each has answer_id, engine, country, locale, stream, executed_at, verdict, quote, start and end (the quote’s place in the answer, in Unicode code points) and reason. corrected and automatic_verdict appear where your team changed the reading.
position.answers[].sourcesThe pages behind this answer’s reading, as url and title. Asky checks every page an answer cites against the reading; where that check has not run yet, these are the pages the engine cited next to the quote.
position.total, position.has_moreHow many answers match, and whether more follow this page.
position.sourcesThe pages behind this entry’s readings under your models and markets, those behind the most readings that work against the entry first, up to 25: url, title, site (internal, competitor or third_party), competitor on a competitor’s page, says, partly and counter (how many answers each), and models.
position.sources_totalHow many pages are behind this entry’s readings.
position.sources_basisWhere the pages come from: checks when Asky read the cited pages for at least one reading, or placement when the pages the engine cited right next to each quote stand in for every reading.
position.sources_checkedWhether the pages are settled. Until then they may still change. A scan is published once its answers are checked, so this is almost always true.

A scan_id or position_id that is not part of this brand returns not_found: “Not found.” verdict without position_id returns invalid_input. One answer in full is the answer endpoint; how AI entries the brand overall is the positioning endpoint.

Last updated on