Refiner | Composio Docs

Overview

SLUG: REFINER

Description

Refiner is a customer feedback and survey tool designed to help businesses collect and analyze user insights.

Authentication Details

API Key

generic_api_key

stringRequired

Connecting to Refiner

Create an auth config

Use the dashboard to create an auth config for the Refiner toolkit. This allows you to connect multiple Refiner accounts to Composio for agents to use.

Select App

Navigate to Refiner.

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

Create and Get auth config ID

Click “Create Refiner Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using API Key

1 from composio import Composio
2 
3 # Replace these with your actual values
4 refiner_auth_config_id = "ac_YOUR_REFINER_CONFIG_ID" # Auth config ID created above
5 user_id = "0000-0000-0000"  # UUID from database/app
6 
7 composio = Composio()
8 
9 def authenticate_toolkit(user_id: str, auth_config_id: str):
10     # Replace this with a method to retrieve an API key from the user.
11     # Or supply your own.
12     user_api_key = input("[!] Enter API key")
13 
14     connection_request = composio.connected_accounts.initiate(
15         user_id=user_id,
16         auth_config_id=auth_config_id,
17         config={"auth_scheme": "API_KEY", "val": {"generic_api_key": user_api_key}}
18     )
19 
20     # API Key authentication is immediate - no redirect needed
21     print(f"Successfully connected Refiner for user {user_id}")
22     print(f"Connection status: {connection_request.status}")
23     
24     return connection_request.id
25 
26 
27 connection_id = authenticate_toolkit(user_id, refiner_auth_config_id)
28 
29 # You can verify the connection using:
30 connected_account = composio.connected_accounts.get(connection_id)
31 print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Refiner toolkit’s playground

OpenAI (Python)

Anthropic (TypeScript)

Google (Python)

Vercel (TypeScript)

Python

1 from composio import Composio
2 from openai import OpenAI
3 import json
4 
5 openai = OpenAI()
6 composio = Composio()
7 
8 # User ID must be a valid UUID format
9 user_id = "0000-0000-0000"  # Replace with actual user UUID from your database
10 
11 tools = composio.tools.get(user_id=user_id, toolkits=["REFINER"])
12 
13 print("[!] Tools:")
14 print(json.dumps(tools))
15 
16 def invoke_llm(task = "What can you do?"):
17     completion = openai.chat.completions.create(
18         model="gpt-4o",
19         messages=[
20             {
21                 "role": "user",
22                 "content": task,  # Your task here!
23             },
24         ],
25         tools=tools,
26     )
27 
28     # Handle Result from tool call
29     result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30     print(f"[!] Completion: {completion}")
31     print(f"[!] Tool call result: {result}")
32 
33 invoke_llm()

Tool List

REFINER_DELETE_CONTACT

Tool Name: Delete Contact

Description

Tool to delete a specific contact by its identifier. use after confirming the contact's id, email, or uuid.

Action Parameters

string

uuid

string

Action Response

data

objectRequired

error

string

successful

booleanRequired

REFINER_GET_ACCOUNT_INFO

Tool Name: Get Account Info

Description

Tool to fetch refiner account subscription and environment usage details. use when you need to audit your current plan and usage.

Action Parameters

Action Response

data

objectRequired

error

string

successful

booleanRequired

REFINER_GET_CONTACT

Tool Name: Get Contact

Description

Tool to retrieve details of a specific contact by its id. use when you need all stored traits for a known user.

Action Parameters

string

uuid

string

Action Response

data

objectRequired

error

string

successful

booleanRequired

REFINER_GET_CONTACTS

Tool Name: Get Contacts

Description

Tool to retrieve a list of contacts from your refiner account. use when you need to filter or paginate through contacts.

Action Parameters

form_uuid

string

order_by

stringDefaults to first_seen_at

page

integerDefaults to 1

page_cursor

string

page_length

integerDefaults to 50

segment_uuid

string

Action Response

data

objectRequired

error

string

successful

booleanRequired

REFINER_GET_FORMS

Tool Name: Get Forms

Description

Tool to retrieve a list of forms (surveys) from your refiner account with optional filtering and pagination. use when you need to list surveys by state, page, or include extra info/config.

Action Parameters

include_config

boolean

include_info

boolean

list

stringDefaults to all

page

integerDefaults to 1

page_length

integerDefaults to 50

Action Response

data

objectRequired

error

string

successful

booleanRequired

REFINER_GET_REPORTING

Tool Name: Get Reporting

Description

Tool to retrieve aggregated reporting data for surveys including metrics and analytics. use when you need survey analytics over a time range filtered by type, question identifiers, tags, forms, or segments.

Action Parameters

date_range_end

date_range_start

form_uuids

array

question_identifiers

array

segment_uuids

array

tag_uuids

array

type

stringRequired

Action Response

average

number

count

integer

csat

integer

data

object

datapoints

integer

date_range_end

Required

date_range_start

Required

error

string

nps

integer

responses

integer

successful

booleanRequired

sum

integer

views

integer

REFINER_GET_RESPONSES

Tool Name: Get Survey Responses

Description

Tool to retrieve all survey responses from your refiner account with optional filtering and pagination. use after confirming survey creation to pull response data.

Action Parameters

date_range_end

date_range_start

form_uuid

string

form_uuids

array

include

stringDefaults to completed

page

integerDefaults to 1

page_cursor

string

page_length

integerDefaults to 50

string

segment_uuid

string

segment_uuids

array

with_attributes

boolean

Action Response

data

objectRequired

error

string

successful

booleanRequired

REFINER_GET_SEGMENTS

Tool Name: Get Segments

Description

Tool to retrieve a list of user segments from your refiner account. use when you need to view or paginate segments.

Action Parameters

page

integerDefaults to 1

page_cursor

string

page_length

integerDefaults to 50

Action Response

data

objectRequired

error

string

successful

booleanRequired

REFINER_TRACK_EVENT

Tool Name: Track Event

Description

Tool to record a user event by name for a user identified via user id or email. use after confirming the identifier and event name.

Action Parameters

string

event

stringRequired

string

Action Response

data

objectRequired

error

string

successful

booleanRequired

REFINER_UPDATE_CONTACT

Tool Name: Update Contact

Description

Tool to update an existing contact's attributes or account. use when you have a contact `id` or `email` and want to modify traits or grouping.

Action Parameters

account

object

attributes

object

string

Action Response

data

objectRequired

error

string

successful

booleanRequired