Attest

Tools 8

• List Boards

  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'.

• Get Board

  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 Key Findings

  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 Survey Responses

  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 both studyId AND a single surveyId. 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 filter 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. Set raw: true only when the user genuinely needs raw, respondent-by-respondent data (e.g. to export it): the response is then the raw per-respondent records exactly as the API returns them (each with its outcome, demographics and per-question answers) rather than aggregates. This can be a large payload, so keep the default aggregated view for normal analysis and narrow it with cardIds / an EFL filter / outcomes when you can.

• Search Studies

  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.

• Get Study Structure

  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. 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 Demographics

  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 Segments

  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 filter 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.