List conversations

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'

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()

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();

{
  "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
}

GET

hc-interactions

public

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'

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()

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();

{
  "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
}

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. It pulls data out of Fini and does not change agent behavior. Results are sorted by latest message time, newest first.

Use 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. If you need to send a new turn into Fini, use Generate Answer. This page is export-only.

Headers

string

required

Bearer token containing your Fini workspace API key. Format: Bearer fini_... The key needs read scope.

Query parameters

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.

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.

integer

default:"50"

Maximum number of conversations to return. Minimum 1, maximum 100.

string

Conversation ID to paginate from. Pass the nextCursor or prevCursor value returned by the previous response.

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.

string

Optional agent ID filter. When provided, only conversations for that agent are returned.

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.

array

Optional comma-separated channel filter.

string

Case-insensitive text filter over user messages. Matches conversations where at least one user message contains the provided text.

string

Case-insensitive text filter over Fini bot messages. Matches conversations where at least one Fini-authored answer contains the provided text.

integer

Filter by CSAT rating. Accepted values are integers from 0 through 5.

string

Case-insensitive substring to find in customer messages. The value can contain up to 100 characters. Literal % and _ characters are rejected.

string

Case-insensitive substring to find in Fini-generated agent messages. The value can contain up to 100 characters. Literal % and _ characters are rejected.

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.

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.

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'

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()

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();

Response

array

Array of PublicConversation objects returned for the requested window and filters. See PublicConversation.

boolean

Whether more results exist beyond the current page.

string | null

Cursor to use when paginating forward. null if there is no next page.

string | null

Cursor to use when paginating backward. null if there is no previous page.

{
  "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
}

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 for the full list of causes.

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

PublicConversation

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

PublicEvent

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.

UserAttributeExecution

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.

ExposedFunctionExecution

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.

RuleNodeExecution

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.

RuleToolExecution

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.

FunctionExecution

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.

PublicArticle

Field	Type	Description
`id`	string	Article ID.
`title`	string	Article title.
`documentUrl`	string \| null	Source document URL when available.

PublicSubfolder

Field	Type	Description
`id`	string	Folder ID.
`title`	string	Folder title.

PublicTag

Field	Type	Description
`id`	string	Tag ID.
`name`	string	Tag name.
`groupId`	string \| null	Parent tag-group ID when one exists.

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

400 Bad Request

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.

401 Unauthorized

The API key is missing, malformed, revoked, or invalid. Confirm you are sending Authorization: Bearer fini_... with the full key.

403 Forbidden

The API key does not include the read scope required for this route.

429 Too Many Requests

You exceeded the rate limit. Back off and retry with your own client-side policy. See Rate limits.

500 Internal Server Error

Fini failed to fulfill the request. Retry once, then contact support if the error persists.

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.

​Headers

​Query parameters

​Response

​Field semantics

​Conversation timestamps

​userAttributes

​csatRating

​Event roles

​Event types

​Nested objects

​Pagination

​Errors

​Rate limits

Headers

Query parameters

Response

Field semantics

Conversation timestamps

userAttributes

csatRating

Event roles

Event types

Nested objects

Pagination

Errors

Rate limits