> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atako.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Refiner

> Connect Refiner to your Atako agents — 9 read and 5 write actions.

Let your agents read survey responses, NPS / CSAT reports, forms, contacts and segments in Refiner, identify contacts with their traits, track events, tag responses and add contacts to manual segments.

## Connection

* **Authentication**: API key (Refiner API key).

> [!NOTE]
>
> In Refiner: Settings → Global Settings → API Keys → create a key (give it a name such as "Atako") and copy it. A key belongs to one environment (the default one is named "Environment #1"): create it in the environment your agents should work in. Reading and writing use the same key, so grant only the read tools if the agent must not change contacts. API access depends on your Refiner plan: see refiner.io/pricing.
>
> See [Refiner's documentation](https://refiner.io/docs/api/).

## Read actions (9)

| Action | Description |
| - | - |
| `get_account` | Get the Refiner account: the subscription usage (plan, contacts, events, pageviews and survey responses counted, with their limits) and the list of environments \{ uuid, name, … }. No arguments. |
| `get_contact` | Get everything Refiner holds on one contact: uuid, remote\_id, e-mail, display name, first and last seen, attributes, segments and account. Give at least one of: id (string, your own user ID); email (string, e-mail address, the first match when several contacts share it); uuid (string, the Refiner contact UUID from list\_contacts or identify\_contact). |
| `get_reporting` | Get an aggregated report, like the reporting dashboards. Arguments: type (string, required, one of nps (score, promoters, passives, detractors), csat (score and distribution), ratings (average and distribution), distribution (count per answer value), count (views and responses)); all others optional: form\_uuids (array of UUID strings from list\_forms); segment\_uuids (array of UUID strings from list\_segments); question\_identifiers (array of strings, only these questions); date\_range\_start and date\_range\_end (strings, ISO 8601, default: the last 7 days up to the end of today); response\_data (object \{ question identifier: answer }); contact\_data (object \{ trait slug: value }); account\_data (object \{ account trait slug: value }). |
| `list_contacts` | List contacts with their attributes, segments and account: \{ items, pagination }. All arguments optional: search (string, matches e-mail, user ID or name); form\_uuid (string, UUID from list\_forms, only contacts linked to this survey); segment\_uuid (string, UUID from list\_segments); order\_by (string, one of display\_name, email, first\_seen\_at (default), last\_seen\_at, last\_form\_submission\_at); page (integer >= 1); page\_length (integer 1 to 1000, default 100); page\_cursor (string, pagination.next\_page\_cursor of the previous page). |
| `list_form_history` | List the previous versions of a form (survey), newest first: \{ items, pagination }, each version holding a snapshot of its name, configuration and questions. Arguments: form\_uuid (string, UUID from list\_forms, required); page (integer >= 1); page\_length (integer 1 to 1000, default 100). |
| `list_forms` | List the forms (surveys) ordered by name: \{ items, pagination }. Each item has uuid and name. All arguments optional: list (string, one of all, published, drafts, archived, all\_with\_archived; default all); page (integer >= 1); page\_length (integer 1 to 1000, default 100); include\_info (boolean, true adds channels, publication and creation dates, response and view counts, folder and survey page URL); include\_config (boolean, true adds the survey configuration and each question under elements: large). The uuid is the form\_uuid of list\_responses, get\_reporting, list\_contacts and list\_form\_history. |
| `list_responses` | List survey responses (and optionally views), newest first: \{ items, pagination }. Each item has the form, the answers under data (question identifier → answer) and the contact. All arguments optional: form\_uuid (string, UUID from list\_forms); form\_uuids (array of UUID strings, several surveys); segment\_uuid (string, UUID from list\_segments); segment\_uuids (array of UUID strings); date\_range\_start and date\_range\_end (strings, ISO 8601, YYYY-MM-DD or YYYY-MM-DD hh:mm:ss); include (string, one of completed (default), partials, all (also dismissed views)); search (string, matches the contact user ID, UUID, e-mail or name); response\_data (object \{ question identifier: answer }, e.g. \{ "nps": 9 }); contact\_data (object \{ trait slug: value }); account\_data (object \{ account trait slug: value }), the three filters need every key to match; with\_attributes (boolean, true adds all contact attributes); page (integer >= 1); page\_length (integer 1 to 1000, default 100); page\_cursor (string, pagination.next\_page\_cursor of the previous page, recommended above 10,000 items). The response uuid is what tag\_response takes. |
| `list_segments` | List the segments ordered by name: \{ items, pagination }, each with uuid, name and is\_manual (true = contacts are added by hand or through add\_contact\_to\_segment). All arguments optional: page (integer >= 1); page\_length (integer 1 to 1000, default 100). |
| `verify_key` | Check the API key and return the environment it belongs to: \{ project\_uuid, project\_name, message }. No arguments. |

## Write actions (5)

| Action | Description |
| - | - |
| `add_contact_to_segment` | Add a contact to a MANUAL segment (a contact that does not exist yet is created). Returns \{ message, contact\_uuid, segment\_uuid }. Arguments: segment\_uuid (string, UUID of a segment with is\_manual true, from list\_segments, required); id (string, your own user ID) and/or email (string): at least one is required. |
| `identify_contact` | Create a contact or update its traits (like identify in the Refiner JavaScript client; the user ID or e-mail is the key, so the same ID updates the same contact). Returns \{ message, contact\_uuid }. Refiner applies it with a delay: the contact and its traits can take about 10 minutes to show in get\_contact or the Refiner app. Arguments: id (string, your own user ID) and/or email (string): at least one is required; traits (object \{ slug: value } with string (up to 4 KB), number or boolean values; a slug ending in \_at is parsed as a date, e.g. created\_at: "2026-10-23"; "name" sets the display name; any slug is created on the fly); account (object \{ id (string, required), name (string), traits (object \{ slug: value }, account traits, same value types) } to group the contact under a company). Traits you do not send are left unchanged. |
| `remove_contact_from_segment` | Remove a contact from a MANUAL segment (the contact and its responses are kept). Arguments: segment\_uuid (string, UUID of a segment with is\_manual true, from list\_segments, required); id (string, your own user ID) and/or email (string): at least one is required. |
| `tag_response` | Add tags to an existing survey response. Arguments: uuid (string, the response UUID from list\_responses, required); tags (array of strings, 1 to 20 tag names, required). Returns \{ message }. |
| `track_event` | Record an event for a contact (a contact that does not exist yet is created). Returns \{ message }. Refiner shows the event after a delay of about 10 minutes. Arguments: event (string, the event name, required); id (string, your own user ID) and/or email (string): at least one is required. |

## Permissions

Every action above must be explicitly granted to an agent before it can be used. See [Permissions](https://docs.atako.ai/integrations/permissions.md) for the grant model and [Security](https://docs.atako.ai/integrations/security.md) for how credentials are protected.

***

*Last reviewed against the provider API: October 2026.*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.