Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Refiner

Scalekit connector
Open markdown

The Refiner connector lets your AI agent act in each user's Refiner account. Each user connects their own Refiner access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 19 tools.

Tools
19
What they doRead · write · destructive
9 · 8 · 29 read8 write2 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Refiner connection

    In AgentKit > Connections, create a Refiner connection. The name you give it is the connection_name your code passes. See Configure connections.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'refiner'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Refiner:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'refiner_get_account_info',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Refiner credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • refiner_get_account_infoGet the Refiner account's subscription plan, usage counters and environments.Read-only

    Get Account Info

    Get the Refiner account's subscription plan, usage counters and environments. Returns plan, monthly tracked users, events, page views and survey responses with their limits, plus each environment's uuid, name and usage. Use for usage and limit checks. Use refiner_get_environment to identify the environment of the API key.

    Inputs

    This tool takes no inputs.

  • refiner_get_contactGet everything Refiner stores about one contact.Read-only

    Get Contact

    Get everything Refiner stores about one contact. Returns uuid, remote_id, email, display_name, first and last seen, attributes, segments and account. Use when you know the contact's ID, email or Refiner UUID. Use refiner_list_contacts to search.

    Inputs

    emailstring
    Email address of the contact; use when you have no user ID. Example: jane@awesome.com
    idstring
    Your own user ID for the contact, the same ID used with identify user. Example: user_123
    uuidstring
    Refiner-generated contact UUID returned by identify user. Example: 15cce3d0-ed5d-11ea-aaef-e58a2a43e996
  • refiner_get_environmentVerify the API key and return the Refiner environment it belongs to.Read-only

    Get Environment

    Verify the API key and return the Refiner environment it belongs to. Returns project_uuid, project_name and an authentication message. Use to confirm the connection works. Use refiner_get_account_info for plan and usage.

    Inputs

    This tool takes no inputs.

  • refiner_get_form_historyList previous versions of a survey.Read-only

    Get Form History

    List previous versions of a survey. Returns an items array of versions with uuid, action, created_at and a snapshot of name, config, channels and question elements, plus a pagination object. Use refiner_list_forms to find the form_uuid.

    Inputs

    form_uuidstringrequired
    UUID of the survey. Example: 3894dc20-8fe9-11ea-892e-d13af52e06ae
    pageinteger
    Page number for numeric pagination, starting at 1. Example: 2
    page_lengthinteger
    Number of items per page, up to 1000 (server default 100). Example: 50
  • refiner_get_reportingGet aggregated survey reporting for a date range.Read-only

    Get Reporting

    Get aggregated survey reporting for a date range. Returns figures for the chosen type: nps (detractors, passives, promoters, nps score), csat (distribution and csat score), ratings (distribution, sum, average), distribution (value counts) or count (views and responses), plus the date range used. Use for summary metrics. Use refiner_list_responses for individual answers.

    Inputs

    typestringrequired
    Report type to compute. Example: npsone of npscsatratingsdistributioncount
    date_range_endstring
    End of the range, ISO 8601 (server default end of today). Example: 2025-04-18
    date_range_startstring
    Start of the range, ISO 8601 (server default 7 days ago). Example: 2024-12-12
    form_uuidsarray
    UUIDs of surveys to include; omit for all. Example: ["3894dc20-8fe9-11ea-892e-d13af52e06ae"]
    question_identifiersarray
    Only count data points for these question identifiers (slugs); omit for all matching questions. Example: ["nps"]
    segment_uuidsarray
    Only count users in these segment UUIDs. Example: ["0ff87720-9ae5-11ea-bce5-65a395204572"]
    tag_uuidsarray
    Only count responses carrying one of these tag UUIDs. Example: ["4f5637d0-3d0d-11ea-b965-614418dec30c"]
  • refiner_list_contactsList contacts (users) tracked in Refiner.Read-only

    List Contacts

    List contacts (users) tracked in Refiner. Returns an items array of contacts with uuid, remote_id, email, display_name, first and last seen, attributes, segments and account, plus a pagination object. Use to browse or search contacts. Use refiner_get_contact for one known contact.

    Inputs

    form_uuidstring
    Only contacts linked to this survey UUID. Example: 3894dc20-8fe9-11ea-892e-d13af52e06ae
    order_bystring
    Field to sort by (server default first_seen_at). Example: last_seen_atone of display_nameemailfirst_seen_atlast_seen_atlast_form_submission_atdefault first_seen_at
    pageinteger
    Page number for numeric pagination, starting at 1. Example: 2
    page_cursorstring
    Cursor from the previous response's pagination.next_page_cursor. Faster than page numbers for large result sets. Example: eyJpdiI6ImpCMlY3cERCbEo0Qk1Ge
    page_lengthinteger
    Number of items per page, up to 1000 (server default 100). Example: 50
    searchstring
    Only contacts whose email, ID or name matches. Example: jane
    segment_uuidstring
    Only contacts in this segment UUID. Example: 0ff87720-9ae5-11ea-bce5-65a395204572
  • refiner_list_formsList surveys (forms) in the Refiner environment, ordered by name.Read-only

    List Forms

    List surveys (forms) in the Refiner environment, ordered by name. Returns an items array of surveys with uuid and name, and a pagination object. With include_info it adds channels, publish and archive dates, response and view counts, folder and page_url. Use to find a form_uuid for responses, reports and publishing. Use refiner_get_form_history for a survey's past versions.

    Inputs

    include_configinteger
    Set to 1 to include each survey's configuration and question elements (server default 0). Can be large. Example: 0one of 01default 0
    include_infointeger
    Set to 1 to add metadata such as creation and publish dates, response and view counts, and folder (server default 0). Example: 1one of 01default 0
    liststring
    Which surveys to return by state (server default all). Example: publishedone of allpublisheddraftsarchivedall_with_archived
    pageinteger
    Page number for numeric pagination, starting at 1. Example: 2
    page_lengthinteger
    Number of items per page, up to 1000 (server default 100). Example: 50
  • refiner_list_responsesList survey responses collected in Refiner, newest first.Read-only

    List Responses

    List survey responses collected in Refiner, newest first. Returns an items array where each item has uuid, timestamps, the survey (uuid, name), the answers in data and the responding contact with account, plus a pagination object with next_page_cursor. Use to read raw answers. Use refiner_get_reporting for aggregated NPS, CSAT or rating figures.

    Inputs

    date_range_endstring
    Only responses before this time, ISO 8601 (YYYY-MM-DD or YYYY-MM-DD hh:mm:ss). Example: 2024-12-31
    date_range_startstring
    Only responses at or after this time, ISO 8601 (YYYY-MM-DD or YYYY-MM-DD hh:mm:ss). Based on last_data_reception_at, or last_shown_at when include is all. Example: 2024-01-01
    form_uuidstring
    UUID of a survey; only responses to that survey are returned. Find it with list forms. Example: 3894dc20-8fe9-11ea-892e-d13af52e06ae
    includestring
    Which responses to return (server default completed): completed, partials (partial plus completed) or all (also dismissed views). Example: partialsone of completedpartialsalldefault completed
    pageinteger
    Page number for numeric pagination, starting at 1. Example: 2
    page_cursorstring
    Cursor from the previous response's pagination.next_page_cursor. Faster than page numbers for large result sets. Example: eyJpdiI6ImpCMlY3cERCbEo0Qk1Ge
    page_lengthinteger
    Number of items per page, up to 1000 (server default 100). Example: 50
    searchstring
    Return only responses whose contact user ID, Refiner UUID, email or name matches. Example: jane@awesome.com
    segment_uuidstring
    UUID of a segment; only responses from users in that segment are returned. Example: 0ff87720-9ae5-11ea-bce5-65a395204572
    tag_uuidstring
    UUID of a response tag; only responses with that tag are returned. Example: 4f5637d0-3d0d-11ea-b965-614418dec30c
    with_attributesinteger
    Set to 1 to include all stored attributes on each response's contact. Example: 1one of 01
All 21 in Customer Support