> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usefini.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List conversations
> Read all Fini conversations for your workspace, sorted newest first, with cursor pagination.
Reads conversations for the workspace tied to your API key. Use it to export conversations into your own systems for analytics, QA review, or downstream processing. This is the read path described on the [API overview](/en/api-reference/overview). It pulls data *out* of Fini and does not change agent behavior. Results are sorted by latest message time, newest first.
<Tip>
Use [List agents](/en/api-reference/list-agents) to look up the `botId` values accepted by this endpoint's optional agent filter. If you already know a conversation ID, use [Get conversation](/en/api-reference/get-conversation). If you need to send a new turn into Fini, use [Generate Answer](/en/api-reference/generate-answer). This page is export-only.
</Tip>
## Headers
<ParamField header="Authorization" type="string" required>
Bearer token containing your Fini workspace API key. Format: `Bearer fini_...` The key needs `read` scope.
</ParamField>
## Query parameters
<ParamField query="since" type="integer">
Inclusive start of the Fini ingestion window in Unix epoch milliseconds. Returns conversations whose `createdAt` is greater than or equal to this value. If omitted, Fini defaults to the last 7 days.
</ParamField>
<ParamField query="until" type="integer">
Inclusive end of the Fini ingestion window in Unix epoch milliseconds. Returns conversations whose `createdAt` is less than or equal to this value. If omitted, Fini defaults to the current time.
</ParamField>
<ParamField query="limit" type="integer" default="50">
Maximum number of conversations to return. Minimum `1`, maximum `100`.
</ParamField>
<ParamField query="cursor" type="string">
Conversation ID to paginate from. Pass the `nextCursor` or `prevCursor` value returned by the previous response.
</ParamField>
<ParamField query="direction" type="string" default="next">
Pagination direction when a cursor is supplied. **Note the inverted mapping:** `next` moves to *older* conversations; `previous` moves back toward *newer* ones. This is because results are sorted newest first, so "next page" goes further back in time.
</ParamField>
<ParamField query="botId" type="string">
Optional agent ID filter. When provided, only conversations for that agent are returned.
</ParamField>
<ParamField query="source" type="array">
Optional comma-separated conversation sources. Supported values: `api`, `widget`, `ui`, `standalone`, `testsuite`, `replay`, `zendesk`, `intercom`, `front`, `hubspot`, `salesforce`, `gorgias`, `livechat`, `slack`, `discord`, `freshdesk`, `freshchat`, and `deskpro`.
</ParamField>
<ParamField query="channel" type="array">
Optional comma-separated channel filter.
</ParamField>
<ParamField query="question" type="string">
Case-insensitive text filter over user messages. Matches conversations where at least one user message contains the provided text.
</ParamField>
<ParamField query="answer" type="string">
Case-insensitive text filter over Fini bot messages. Matches conversations where at least one Fini-authored answer contains the provided text.
</ParamField>
<ParamField query="csatRating" type="integer">
Filter by CSAT rating. Accepted values are integers from `0` through `5`.
</ParamField>
<ParamField query="question" type="string">
Case-insensitive substring to find in customer messages. The value can contain up to 100 characters. Literal `%` and `_` characters are rejected.
</ParamField>
<ParamField query="answer" type="string">
Case-insensitive substring to find in Fini-generated agent messages. The value can contain up to 100 characters. Literal `%` and `_` characters are rejected.
</ParamField>
<Warning>
The `since` / `until` window cannot exceed **90 days**, and `since` must be strictly earlier than `until`. A request where `since == until` is rejected for the same reason and returns `400 Bad Request`.
</Warning>
<Note>
Additional behavior worth knowing:
* The endpoint only returns conversations where **Fini has touched the conversation**.
* `since` and `until` filter the Fini ingestion timestamp in `createdAt`. They do not filter `externalCreatedAt` or event timestamps.
* `source` and `channel` accept either comma-separated values or repeated query params if your HTTP client sends arrays.
* `question` and `answer` are each limited to 100 non-blank characters. They cannot include `%`, `_`, or control characters.
* When both message filters are supplied, a conversation must contain a matching customer message and a matching Fini-generated agent message.
</Note>
<RequestExample>
~~~bash cURL theme={null}
curl --request GET \
--url 'https://api-prod.usefini.com/v2/hc-interactions/public?limit=25&channel=chat&source=widget,ui&question=refund' \
--header 'Authorization: Bearer fini_your_api_key'
~~~
~~~python Python theme={null}
import requests
response = requests.get(
"https://api-prod.usefini.com/v2/hc-interactions/public",
headers={"Authorization": "Bearer fini_your_api_key"},
params={
"limit": 25,
"channel": "chat",
"source": "widget,ui",
"question": "refund",
},
)
data = response.json()
~~~
~~~javascript Node.js theme={null}
const params = new URLSearchParams({
limit: "25",
channel: "chat",
source: "widget,ui",
question: "refund",
});
const response = await fetch(
`https://api-prod.usefini.com/v2/hc-interactions/public?${params.toString()}`,
{
headers: {
Authorization: "Bearer fini_your_api_key",
},
}
);
const data = await response.json();
~~~
</RequestExample>
## Response
<ResponseField name="interactions" type="array">
Array of `PublicConversation` objects returned for the requested window and filters. See [PublicConversation](#nested-objects).
</ResponseField>
<ResponseField name="hasMore" type="boolean">
Whether more results exist beyond the current page.
</ResponseField>
<ResponseField name="nextCursor" type="string | null">
Cursor to use when paginating forward. `null` if there is no next page.
</ResponseField>
<ResponseField name="prevCursor" type="string | null">
Cursor to use when paginating backward. `null` if there is no previous page.
</ResponseField>
<ResponseExample>
~~~json 200 OK theme={null}
{
"interactions": [
{
"id": "a5221094-72d4-4b9c-8d30-2f785b108bd9",
"createdAt": 1785228932000,
"externalCreatedAt": 1785228931000,
"source": "widget",
"channel": "chat",
"status": "resolved",
"externalId": "widget-conversation-4821",
"url": null,
"subjectPreview": "Refund eligibility",
"hasFeedback": false,
"resolved": true,
"userAttributes": {
"plan": "Pro"
},
"usedArticles": [
{
"id": "fd88d59f-4dd5-4922-a872-6bdd0be20e55",
"title": "Refund policy",
"documentUrl": "https://help.example.com/refunds"
}
],
"usedSubfolders": [
{
"id": "60430f95-ddf8-4105-996a-203aa28dd66f",
"title": "Billing"
}
],
"events": [
{
"id": "5243cbb1-b744-4a60-8062-857bb014acba",
"interactionId": "a5221094-72d4-4b9c-8d30-2f785b108bd9",
"createdAt": 1785228932000,
"role": "user",
"type": "message",
"message": "Can I get a refund for last month's charge?",
"externalId": "message-104",
"externalCreatedAt": 1785228931000,
"csatRating": null,
"feedback": null,
"approved": null,
"resolved": null,
"attachments": [
{
"gcpUrl": "https://storage.googleapis.com/example-public/receipt.pdf",
"gcpPath": "receipts/receipt.pdf",
"originalUrl": "https://files.example.com/receipt.pdf",
"contentType": "application/pdf",
"expiresAt": 1785315332000,
"sizeBytes": 48321
}
],
"tags": [
{
"id": "b08ee98d-f987-48c9-8f19-8fc12c6f8a0b",
"name": "Refund request",
"groupId": "c827a4bd-b32a-474a-af86-b2f24190f39a"
}
],
"usedArticles": [
{
"id": "fd88d59f-4dd5-4922-a872-6bdd0be20e55",
"title": "Refund policy",
"documentUrl": "https://help.example.com/refunds"
}
]
},
{
"id": "c5df46c8-4d6f-468c-a8bf-bc2e59ea1249",
"interactionId": "a5221094-72d4-4b9c-8d30-2f785b108bd9",
"createdAt": 1785228940000,
"role": "finibot",
"type": "message",
"message": "Refunds are available within 30 days.",
"externalId": "message-105",
"externalCreatedAt": 1785228940000,
"csatRating": null,
"feedback": null,
"approved": null,
"resolved": null,
"attachments": [
{
"gcpUrl": "https://storage.googleapis.com/example-public/policy.pdf",
"gcpPath": "policies/refund-policy.pdf",
"originalUrl": "https://help.example.com/refund-policy.pdf",
"contentType": "application/pdf",
"expiresAt": 1785315340000,
"sizeBytes": 93214
}
],
"tags": [
{
"id": "b08ee98d-f987-48c9-8f19-8fc12c6f8a0b",
"name": "Refund request",
"groupId": "c827a4bd-b32a-474a-af86-b2f24190f39a"
}
],
"usedArticles": [
{
"id": "fd88d59f-4dd5-4922-a872-6bdd0be20e55",
"title": "Refund policy",
"documentUrl": "https://help.example.com/refunds"
}
]
}
]
}
],
"hasMore": false,
"nextCursor": null,
"prevCursor": null
}
~~~
</ResponseExample>
<Note>
The `400 Bad Request` `message` varies by cause. It may quote the specific rule that failed (`since`/`until` range > 90 days, `since >= until`, invalid UUID, etc.). See [Errors](#errors) for the full list of causes.
</Note>
## Field semantics
### Conversation timestamps
`createdAt` is the Fini ingestion timestamp: when Fini created the stored conversation record. The `since` and `until` query parameters filter this field.
`externalCreatedAt` is the timestamp reported by the source provider for the conversation. It is `null` when the source does not provide one. Use it to place delayed or backfilled conversations on the provider's original timeline after retrieving them by their Fini ingestion window.
Events follow the same distinction. `events[].createdAt` is when Fini stored the event, while `events[].externalCreatedAt` is the provider-side timestamp for that specific event when available.
### userAttributes
`userAttributes` is an open-ended object. Fini returns the attributes captured on the conversation as-is, so the schema is **consumer-defined** and can vary by workspace. If your bots populate CRM-specific or workflow-specific fields, they appear here unchanged.
### csatRating
`events[].csatRating` is passed through from the stored event data:
* `null` means no CSAT value is present on that event
* numeric values are returned as stored
If your upstream data writes `0`, the API returns `0`. Do **not** automatically treat `0` as "unrated" unless that is how your own channel or integration encodes the value.
### Event roles
`events[].role` can currently be:
| Value | Meaning |
| - | - |
| `user` | A message from the end user or customer. |
| `agent` | A human agent message synced from the connected provider. |
| `finibot` | A Fini-generated message or system action. |
| `otherbot` | A non-Fini bot or automation message from the upstream provider. |
### Event types
`events[].type` can currently be:
| Value | Meaning |
| - | - |
| `message` | A normal message event. |
| `internalnote` | A private/internal note rather than a customer-visible message. |
| `no_reply` | Fini decided not to send a reply. |
| `silent_escalation` | Fini escalated without posting a visible reply. |
| `debounce` | A debounce/system event used internally around message timing. |
| `widget_form` | A widget form conversation event. |
## Nested objects
<AccordionGroup>
<Accordion title="PublicConversation" icon="comments">
| Field | Type | Description |
| - | - | - |
| `id` | string | Conversation ID. Also used as the pagination cursor. |
| `createdAt` | epoch ms | Fini ingestion timestamp. The `since` and `until` parameters filter this field. |
| `externalCreatedAt` | epoch ms \| null | Provider-side conversation timestamp when available. |
| `source` | string | Source of the conversation, such as `api`, `widget`, `ui`, or a connected integration. |
| `channel` | string | Channel type. Currently `email` or `chat`. |
| `status` | string \| null | Human-readable conversation status, if available. |
| `externalId` | string \| null | External system identifier when the conversation came from an integration. |
| `url` | string \| null | Link back to the source conversation, when available. |
| `subjectPreview` | string \| null | Short subject or preview string for the conversation. |
| `hasFeedback` | boolean | Whether the conversation has feedback attached. |
| `resolved` | boolean \| null | Whether the conversation has been marked resolved. |
| `userAttributes` | object \| null | User attributes captured on the conversation. See [Field semantics](#userattributes). |
| `usedArticles` | `PublicArticle[]` | Public article references used during the conversation. |
| `usedSubfolders` | `PublicSubfolder[]` | Public subfolder references used during the conversation. |
| `events` | `PublicEvent[]` | Chronological event stream for the conversation. |
</Accordion>
<Accordion title="PublicEvent" icon="message">
| Field | Type | Description |
| - | - | - |
| `id` | string | Event ID. |
| `interactionId` | string | Conversation ID that owns the event. |
| `createdAt` | epoch ms | When Fini stored the event. |
| `role` | string | One of the event roles documented above. |
| `type` | string | One of the event types documented above. |
| `message` | string \| null | Message text, when the event carries message content. |
| `externalId` | string \| null | Provider-side message ID when available. |
| `externalCreatedAt` | epoch ms \| null | Provider-side timestamp when available. |
| `csatRating` | number \| null | Numeric CSAT value if one was stored on the event. |
| `feedback` | string \| null | Free-text feedback note attached to the event. |
| `approved` | boolean \| null | Thumbs up (`true`), thumbs down (`false`), or unrated (`null`). |
| `resolved` | boolean \| null | Resolution flag for negatively rated or flagged events. |
| `attachments` | array | File attachments on the event. Passed through from stored event data; commonly includes fields like `originalUrl`, `contentType`, `expiresAt`, `sizeBytes`, and storage URLs. |
| `tags` | `PublicTag[]` | Tags attached to the event. |
| `usedArticles` | `PublicArticle[]` | Articles retrieved for that specific event. |
| `executedUserAttributes` | `UserAttributeExecution[]` \| null | User-attribute tools executed for the event. Optional when execution metadata was not recorded. |
| `executedRuleResults` | `RuleNodeExecution[]` \| null | Rule nodes executed for the event. Optional when rule execution metadata was not recorded. |
</Accordion>
<Accordion title="UserAttributeExecution" icon="user-gear">
| Field | Type | Description |
| - | - | - |
| `id` | string | User-attribute tool ID. |
| `name` | string | Tool name. |
| `success` | boolean | Whether the tool completed successfully. |
| `extractedData` | object | Attribute values extracted by the tool. |
| `results` | `ExposedFunctionExecution[]` | Optional results from API-function steps executed by the tool. |
</Accordion>
<Accordion title="ExposedFunctionExecution" icon="code">
| Field | Type | Description |
| - | - | - |
| `id` | string | Optional API-function configuration ID. |
| `name` | string | API-function step name. |
| `success` | boolean | Whether the step completed successfully. |
| `error` | string | Optional error message when the step failed. |
</Accordion>
<Accordion title="RuleNodeExecution" icon="diagram-project">
| Field | Type | Description |
| - | - | - |
| `id` | string | Rule node ID. |
| `name` | string | Rule node name. |
| `type` | string | Node type: `SEQUENCE`, `SELECTOR`, `ACTION`, `CONDITION`, or `WIDGET_FORM_RENDERER`. |
| `success` | boolean | Whether the node completed successfully. |
| `subType` | string | Optional action subtype: `LLM_EXTRACTION`, `TOOL_CALL`, `PROMPT_INJECTION`, `WIDGET_FORM_VALIDATION_ERROR`, or `SEND_MESSAGE`. |
| `terminate` | boolean | Optional flag indicating that rule execution terminated at this node. |
| `result` | any | Optional node-specific result payload. |
| `toolResult` | `RuleToolExecution` | Optional tool execution details for action nodes. |
| `overrideMainPrompt` | boolean | Optional flag indicating that the node overrides the main prompt. |
| `systemFields` | object | Optional system output. May contain `ticketId`, `ticketNumber`, `ticketUrl`, and boolean `escalationActive` fields. |
</Accordion>
<Accordion title="RuleToolExecution" icon="wrench">
| Field | Type | Description |
| - | - | - |
| `id` | string | Tool ID. |
| `name` | string | Tool name. |
| `success` | boolean | Whether the tool completed successfully. |
| `extractedData` | object | Values extracted by the tool. |
| `attributeLlmPolicy` | object | Map of attribute names to boolean LLM-exposure policies. |
| `results` | `FunctionExecution[]` | Optional API-function step results. |
</Accordion>
<Accordion title="FunctionExecution" icon="code-branch">
| Field | Type | Description |
| - | - | - |
| `id` | string | Optional API-function configuration ID. |
| `name` | string | API-function step name. |
| `stepNumber` | number | Execution order of the API-function step. |
| `success` | boolean | Whether the step completed successfully. |
| `resolvedUrl` | string | Optional resolved request URL. |
| `resolvedHeaders` | any | Optional resolved request headers. |
| `resolvedBody` | any | Optional resolved request body. |
| `data` | any | Optional response data. |
| `error` | string | Optional execution error. |
| `extractedData` | object | Optional values extracted from the response. |
</Accordion>
<Accordion title="PublicArticle" icon="book-open">
| Field | Type | Description |
| - | - | - |
| `id` | string | Article ID. |
| `title` | string | Article title. |
| `documentUrl` | string \| null | Source document URL when available. |
</Accordion>
<Accordion title="PublicSubfolder" icon="folder">
| Field | Type | Description |
| - | - | - |
| `id` | string | Folder ID. |
| `title` | string | Folder title. |
</Accordion>
<Accordion title="PublicTag" icon="tag">
| Field | Type | Description |
| - | - | - |
| `id` | string | Tag ID. |
| `name` | string | Tag name. |
| `groupId` | string \| null | Parent tag-group ID when one exists. |
</Accordion>
</AccordionGroup>
## Pagination
Cursor pagination is relative to the current cursor, not to time:
* pass `nextCursor` with `direction=next` to move to **older** conversations
* pass `prevCursor` with `direction=previous` to move back toward **newer** conversations
If you omit `cursor`, the API starts from the newest matching conversations in the requested time window.
## Errors
<AccordionGroup>
<Accordion title="400 Bad Request" icon="circle-exclamation">
The query parameters are invalid. Common causes: an invalid UUID, `since` later than or equal to `until`, or a time window larger than 90 days. The response `message` quotes the specific rule that failed.
</Accordion>
<Accordion title="401 Unauthorized" icon="lock">
The API key is missing, malformed, revoked, or invalid. Confirm you are sending `Authorization: Bearer fini_...` with the full key.
</Accordion>
<Accordion title="403 Forbidden" icon="shield-halved">
The API key does not include the `read` scope required for this route.
</Accordion>
<Accordion title="429 Too Many Requests" icon="gauge-high">
You exceeded the rate limit. Back off and retry with your own client-side policy. See [Rate limits](#rate-limits).
</Accordion>
<Accordion title="500 Internal Server Error" icon="triangle-exclamation">
Fini failed to fulfill the request. Retry once, then contact support if the error persists.
</Accordion>
</AccordionGroup>
## Rate limits
The API applies a global throttle of **100 requests per 60 seconds**.
Two caveats:
* this endpoint does not currently document `X-RateLimit-*` headers
* this endpoint does not currently document a `Retry-After` header contract
If you receive `429`, back off and retry with your own client-side policy.
## Related topics
- [Get conversation](/en/api-reference/get-conversation.md)
- [Delete conversation](/en/api-reference/delete-conversation.md)
- [List agents](/en/api-reference/list-agents.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
Conversations