Attest

Get a board by ID. Returns the full board including chart items, layout, settings, and permissions. Board items of type DATA are linked to specific questions. The API calls these 'reports' but users know them as 'boards'. The response includes a `boardUrl` to open the board in the dashboard.

get_board

Get available demographics for filtering survey responses by country and language. Returns the valid demographic field names (e.g., gender_v2, home_region, age) and their allowed values for the specified country/language. ALWAYS call this before writing EFL queries to ensure you use the correct field names and values. You MUST call get_study_structure first and read the country/language keys from its wave audiences - do not guess them. Pass keys like 'GB_ENG', 'US_ENG'.

get_demographics

Get the auto-generated key findings board for a study's wave. Returns the headline insights and supporting charts Attest surfaces for that wave. Requires studyId and waveTimestamp (epoch milliseconds): use the `waveTimestamp` the study structure reports for that wave's survey verbatim - do not derive it from a date yourself. The response includes a `keyFindingsUrl` to open the key findings in the dashboard.

get_key_findings

List a study's saved audience segments - the named custom filters a user has saved in the dashboard (e.g. 'Gen Z', 'Dog owners', 'Lapsed customers'). Returns each segment's name, id, scope, and its underlying EFL query. When the user asks to filter by a specific or named audience or cohort (whether or not they call it a 'segment'), check here first: match their wording to a saved segment and pass that segment's EFL as the efl argument to get_survey_responses, rather than composing your own filter for an audience they may already have defined. Covers both study-specific segments and the organisation's shared 'library' segments. If none matches, fall back to building an EFL yourself - do not invent a segment. Requires the study id - get it from search_studies first.

get_segments

Get a study's structure as it was actually rendered to respondents - the basis for interpreting its results. Returns the study's surveys (one per wave/audience, each with a waveIndex where 0 is the oldest and -1 the latest), the audiences, and the questions with their answer options. Each option carries the template id used in EFL filters (cards.<nodeId>.answers.*.id) and flags that explain the data: `qualifier` (a screening answer - only respondents who pick it continue), `forwarded`/`forwardedFrom` (forward answers - the option appears only because the respondent chose it earlier), `omittedFrom` (audiences this question or option was hidden from - localisation), `pipedFrom` (piping), and `randomized`. Defaults to the full aggregate across waves; use the query parameters to drill into a specific wave, survey, audience, market or question. Unless you set node_shape, questions come back as a light outline: ids, types, titles and answer options with their ids and text, enough to find questions and build filters (omitting node_shape here gives the light outline, not the full shape its own description mentions). To work out why a result looks the way it does, fetch the questions concerned with node_shape: full and their node_ids to see the flags above. The flags that carry ids (omittedFrom = audience ids, forwardedFrom/pipedFrom = question ids) reference the audiences and questions listed in the same response, so resolve them there. Each survey also carries a `waveTimestamp` (epoch milliseconds) - pass it straight to the key-findings tool rather than deriving it from the publish date.

get_study_structure

Get survey response data (results) for a study. By default returns respondent answers aggregated by question with response counts and answer texts. IMPORTANT: Always provide studyId AND exactly one survey ID in surveyIds. Get survey IDs from the study structure (each wave lists its surveys). If you need data from multiple surveys, make parallel calls - one per survey - rather than passing a comma-separated list (parallel is much faster). To filter respondents - by who they are or how they answered - build a single EFL query string and pass it as the efl argument (e.g. demographics.age >= 18 AND demographics.age <= 30). There is no structured or faceted filter input: express every condition inside that one string, and when comparing groups make one filtered call per group rather than one unfiltered call. Get the study structure first to find survey IDs, card GUIDs, and answer IDs. The response reports respondent outcomes and the qualified base size, and flags a small base - judge reliability against it. Screened-out respondents are included by default and can inflate counts on early qualifying questions; use the outcomes filter to exclude them. Open-text questions return every verbatim answer by default. When the user only needs the gist, set openTextLimit to return fewer; the response then gives the full total alongside, so treat the answers as a sample of it. Set raw: true only when the user genuinely needs raw, respondent-by-respondent data (e.g. to export it): the response is then one page of the raw per-respondent records exactly as the API returns them (each with its outcome, demographics and per-question answers) rather than aggregates. To fetch the next page, repeat the call with the same arguments and the cursor the page returns, until it reports no more. Page size and cursor apply only to raw: true; the aggregated view always covers every respondent. Each record is large, so keep the default aggregated view for normal analysis and narrow it with cardIds / an EFL filter / outcomes when you can.

get_survey_responses

List the boards (dashboards) available for a study. Pass studyId to scope to one study. Returns a summary per board (id, title, studyId, itemCount, boardUrl) - use get_board for the full board. The API calls these 'reports' but users know them as 'boards'.

list_boards

Search and list studies/surveys by name, status, or other filters. Use this whenever the user wants to find, list, or browse the studies or surveys they've run or own - these are the research projects themselves (boards are dashboards built on a study's results, not the list of studies). When filtering by status, use only the values listed in the status field's enum - its prose description and examples can be out of date, so trust the enum over them. Map the user's everyday words (open, running, finished) onto the closest enum value rather than passing a word that isn't in the enum. Returns study summaries with IDs, titles, status, and audience info. Draft studies are not included - this connection exposes published results only.

search_studies