List conversations

curl --request GET \
  --url 'https://api-prod.usefini.com/v2/hc-interactions/public?limit=25&channel=chat&source=widget,ui' \
  --header 'Authorization: Bearer fini_your_api_key'

{
  "interactions": [
    {
      "id": "0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8",
      "createdAt": 1747075200000,
      "source": "widget",
      "channel": "chat",
      "status": "Escalated to Human Agent",
      "externalId": null,
      "url": "https://app.usefini.com/dashboard/inbox/0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8",
      "subjectPreview": "How do I cancel my plan?",
      "hasFeedback": true,
      "resolved": true,
      "userAttributes": {
        "plan": "Pro",
        "country": "US"
      },
      "usedArticles": [
        {
          "id": "7f5392e5-dc7d-4558-8860-cf3ea4b32f94",
          "title": "Canceling your subscription",
          "documentUrl": null
        }
      ],
      "usedSubfolders": [
        {
          "id": "2f4df245-b2a1-47f1-bb21-398c8ab00b56",
          "title": "Billing"
        }
      ],
      "events": [
        {
          "id": "2d3d5f6d-0fbc-4a6d-874d-4e2c632f124a",
          "createdAt": 1747075201000,
          "role": "user",
          "type": "message",
          "message": "How do I cancel my plan?",
          "externalId": null,
          "externalCreatedAt": null,
          "csatRating": null,
          "feedback": null,
          "approved": null,
          "resolved": null,
          "attachments": [],
          "tags": [],
          "usedArticles": []
        },
        {
          "id": "f61a9a11-2c3b-4704-8f57-7078854d87cf",
          "createdAt": 1747075205000,
          "role": "finibot",
          "type": "message",
          "message": "You can cancel from Billing Settings in your account.",
          "externalId": null,
          "externalCreatedAt": null,
          "csatRating": 5,
          "feedback": "Solved my question instantly.",
          "approved": true,
          "resolved": null,
          "attachments": [],
          "tags": [],
          "usedArticles": [
            {
              "id": "7f5392e5-dc7d-4558-8860-cf3ea4b32f94",
              "title": "Canceling your subscription",
              "documentUrl": null
            }
          ]
        }
      ]
    }
  ],
  "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' \
  --header 'Authorization: Bearer fini_your_api_key'

{
  "interactions": [
    {
      "id": "0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8",
      "createdAt": 1747075200000,
      "source": "widget",
      "channel": "chat",
      "status": "Escalated to Human Agent",
      "externalId": null,
      "url": "https://app.usefini.com/dashboard/inbox/0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8",
      "subjectPreview": "How do I cancel my plan?",
      "hasFeedback": true,
      "resolved": true,
      "userAttributes": {
        "plan": "Pro",
        "country": "US"
      },
      "usedArticles": [
        {
          "id": "7f5392e5-dc7d-4558-8860-cf3ea4b32f94",
          "title": "Canceling your subscription",
          "documentUrl": null
        }
      ],
      "usedSubfolders": [
        {
          "id": "2f4df245-b2a1-47f1-bb21-398c8ab00b56",
          "title": "Billing"
        }
      ],
      "events": [
        {
          "id": "2d3d5f6d-0fbc-4a6d-874d-4e2c632f124a",
          "createdAt": 1747075201000,
          "role": "user",
          "type": "message",
          "message": "How do I cancel my plan?",
          "externalId": null,
          "externalCreatedAt": null,
          "csatRating": null,
          "feedback": null,
          "approved": null,
          "resolved": null,
          "attachments": [],
          "tags": [],
          "usedArticles": []
        },
        {
          "id": "f61a9a11-2c3b-4704-8f57-7078854d87cf",
          "createdAt": 1747075205000,
          "role": "finibot",
          "type": "message",
          "message": "You can cancel from Billing Settings in your account.",
          "externalId": null,
          "externalCreatedAt": null,
          "csatRating": 5,
          "feedback": "Solved my question instantly.",
          "approved": true,
          "resolved": null,
          "attachments": [],
          "tags": [],
          "usedArticles": [
            {
              "id": "7f5392e5-dc7d-4558-8860-cf3ea4b32f94",
              "title": "Canceling your subscription",
              "documentUrl": null
            }
          ]
        }
      ]
    }
  ],
  "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

Authorization

string

required

Bearer token containing your Fini workspace API key. Format: Bearer fini_...

Query parameters

since

integer

Start of the time window in Unix epoch milliseconds. If omitted, Fini defaults to the last 7 days.

until

integer

End of the time window in Unix epoch milliseconds. If omitted, Fini defaults to the current time.

limit

integer

default:"50"

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

cursor

string

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

direction

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.

botId

string

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

source

array

Optional comma-separated conversation sources. Common values include api, widget, ui, standalone, testsuite, replay, zendesk, intercom, front, hubspot, salesforce, gorgias, livechat, slack, discord, freshdesk, and freshchat.

channel

array

Optional comma-separated channel filter.

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.
source and channel accept either comma-separated values or repeated query params if your HTTP client sends arrays.

curl --request GET \
  --url 'https://api-prod.usefini.com/v2/hc-interactions/public?limit=25&channel=chat&source=widget,ui' \
  --header 'Authorization: Bearer fini_your_api_key'

Response

interactions

array

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

hasMore

boolean

Whether more results exist beyond the current page.

nextCursor

string | null

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

prevCursor

string | null

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

{
  "interactions": [
    {
      "id": "0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8",
      "createdAt": 1747075200000,
      "source": "widget",
      "channel": "chat",
      "status": "Escalated to Human Agent",
      "externalId": null,
      "url": "https://app.usefini.com/dashboard/inbox/0b8626b0-4cc8-4a3d-8fc2-f18ad1a4a1a8",
      "subjectPreview": "How do I cancel my plan?",
      "hasFeedback": true,
      "resolved": true,
      "userAttributes": {
        "plan": "Pro",
        "country": "US"
      },
      "usedArticles": [
        {
          "id": "7f5392e5-dc7d-4558-8860-cf3ea4b32f94",
          "title": "Canceling your subscription",
          "documentUrl": null
        }
      ],
      "usedSubfolders": [
        {
          "id": "2f4df245-b2a1-47f1-bb21-398c8ab00b56",
          "title": "Billing"
        }
      ],
      "events": [
        {
          "id": "2d3d5f6d-0fbc-4a6d-874d-4e2c632f124a",
          "createdAt": 1747075201000,
          "role": "user",
          "type": "message",
          "message": "How do I cancel my plan?",
          "externalId": null,
          "externalCreatedAt": null,
          "csatRating": null,
          "feedback": null,
          "approved": null,
          "resolved": null,
          "attachments": [],
          "tags": [],
          "usedArticles": []
        },
        {
          "id": "f61a9a11-2c3b-4704-8f57-7078854d87cf",
          "createdAt": 1747075205000,
          "role": "finibot",
          "type": "message",
          "message": "You can cancel from Billing Settings in your account.",
          "externalId": null,
          "externalCreatedAt": null,
          "csatRating": 5,
          "feedback": "Solved my question instantly.",
          "approved": true,
          "resolved": null,
          "attachments": [],
          "tags": [],
          "usedArticles": [
            {
              "id": "7f5392e5-dc7d-4558-8860-cf3ea4b32f94",
              "title": "Canceling your subscription",
              "documentUrl": null
            }
          ]
        }
      ]
    }
  ],
  "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

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	When the conversation was created.
`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.
`createdAt`	epoch ms	When the event was created.
`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.

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.

⌘I

​Headers

​Query parameters

​Response

​Field semantics

​userAttributes

​csatRating

​Event roles

​Event types

​Nested objects

​Pagination

​Errors

​Rate limits

Headers

Query parameters

Response

Field semantics

userAttributes

csatRating

Event roles

Event types

Nested objects

Pagination

Errors

Rate limits