List interactions

Reads interactions for the workspace tied to your API key. Use it to export interactions 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.

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 interactions to return. Minimum 1, maximum 100.

cursor

string

Interaction 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 interactions; 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 interactions for that agent are returned.

source

array

Optional comma-separated interaction sources. Common values include 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 interactions 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 interaction records returned for the requested window and filters.

Show interaction object

string

Interaction ID. Also used as the pagination cursor.

createdAt

integer

Creation time in Unix epoch milliseconds.

source

string

Source of the interaction, such as widget, ui, or a connected integration.

channel

string

Channel type. Currently email or chat.

status

string

Human-readable conversation status, if available. For example: Resolved, Escalated to Human Agent, or Waiting for Customer.

externalId

string

External system identifier when the interaction came from an integration.

url

string

Link back to the source conversation, when available.

subjectPreview

string

Short subject or preview string for the interaction.

hasFeedback

boolean

Whether the interaction has feedback attached.

resolved

boolean

Whether the interaction has been marked resolved.

userAttributes

object

User attributes captured on the interaction, if present. See Field semantics.

usedArticles

array

Public article references used during the interaction. See PublicArticle.

usedSubfolders

array

Public subfolder references used during the interaction. See PublicSubfolder.

events

array

Chronological event stream for the interaction, including user and agent messages. See PublicEvent.

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 interaction 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 interaction event.

Nested objects

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 interactions
pass prevCursor with direction=previous to move back toward newer interactions

If you omit cursor, the API starts from the newest matching interactions 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 have the required scope for the operation, or is scoped to a different workspace than the data you’re requesting.

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.

Documentation Index

​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