> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.flockx.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.flockx.io/_mcp/server.

# List

GET https://api.flockx.io/api/v1/interactions

List interactions for a user.

Reference: https://docs.flockx.io/api-reference/interactions/list-interactions

## Authentication

- `Authorization` header (required) — API Key authentication via header

## Request

### Query parameters

- `size` (integer, optional, default: 50)
- `page` (integer, optional, default: 1)
- `sort_order` (enum, optional, nullable) — Sort order (asc or desc)
  - Allowed values: `asc`, `desc`
- `end_time` (string, required) — Timestamp for the latest interaction to include.
- `start_time` (string, optional, nullable) — Timestamp for the earliest interaction to include. When unset, history extends to the channel's oldest row.
- `source` (enum, optional, nullable) — The source of the interaction.
  - Allowed values: `websocket`, `telegram`, `discord`, `whatsapp`, `sms`
- `agent_id` (string, optional, nullable) — The ID of the agent for which to get interactions.
- `channel_id` (string, optional, nullable) — The ID of the channel for which to get interactions.
- `type` (enum, optional, nullable) — The type of interaction to get.
  - Allowed values: `human`, `meta_ai`, `ai_agent`
- `include_nested_interactions` (boolean, optional, default: false) — Whether to include nested interactions.
- `include_incomplete` (boolean, optional, nullable) — Whether to include incomplete interactions.
- `include_external_agents` (boolean, optional, default: false) — Include channels where external agent participants (e.g., ASI chats) have addresses matching agents in the organization.
- `around_sequence` (integer, optional, nullable) — Return a window of messages centered on this per-channel sequence. Mutually exclusive with before_sequence and after_sequence. Requires channel_id. end_time is still required but ignored.
- `before_sequence` (integer, optional, nullable) — Return messages with sequence strictly less than this value. Replaces page offset. Requires channel_id.
- `after_sequence` (integer, optional, nullable) — Return messages with sequence strictly greater than this value. Replaces page offset. Requires channel_id.
- `include_tool_progress` (boolean, optional, default: false) — Include the latest in-flight tool progress update per running tool call as ephemeral tool_call_update interactions on the first page. Off by default; responses are unchanged unless requested.

## Response

### 200

Successful Response

- `items` (list of Interaction, required)
- `meta` (ItemListMeta, required)

## Errors

### 422 Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

## Types

### Interaction

- `id` (string, required) — The ID of the interaction.
- `created_at` (string, required) — The date and time the interaction was created.
- `channel_id` (string, required) — The ID of the channel.
- `participant` (InteractionParticipant, required) — The participant that sent this interaction.
- `content` (list of InteractionContentItems, required) — The content of the interaction.
- `content_role` (enum, required) — Whether the content is from a user message, intermediate agent reasoning, or final agent response.
  - Allowed values: `user_message`, `agent_response`, `agent_reasoning`, `tool_call`, `tool_call_result`, `tool_call_update`, `internal_error`, `channel_notification`
- `complete` (boolean, required) — Whether the interaction is complete. Incomplete interactions are only included when include_incomplete query parameter is True.
- `metadata` (map from string to any, optional, nullable) — Metadata for the interaction. Assistant agent_response messages may include display_artifacts (canonical artifact cards for this turn) and display_artifact_deletes (deleted artifact id and name pairs).
- `invocation_config` (InvocationConfig, optional, nullable) — Typed user-driven invocation configuration for the turn (model, planner mode, voice, mentions, etc.). Null when no invocation config was set.
- `nested_interactions` (list of Interaction, optional, nullable) — Nested interactions for this interaction. This will only be present when include_nested_interactions is True.
- `interaction_id` (string, optional, nullable) — Groups all events from a single user turn. Use this to group related messages.
- `sequence` (integer, optional, nullable) — Per-channel monotonically increasing sequence number for stable ordering. Null for messages persisted before sequencing was introduced.
- `span_id` (string, optional, nullable) — Unique identifier for this specific event in the interaction tree.
- `parent_span_id` (string, optional, nullable) — The span_id of the parent event, for hierarchical grouping.
- `organization_id` (string, optional, nullable) — The ID of the organization that owns the channel this interaction belongs to. Used for business intelligence filtering in Kibana.
- `organization_application` (string, optional, nullable) — The application that created the organization (e.g., 'flockx', 'asi_one', 'fetch_business'). Used for filtering interactions by product in Kibana.
- `reactions` (list of MessageReactionSummary, optional, nullable) — Emoji reaction summaries for this interaction.
- `mention_invite_prompt_dismissed` (boolean, optional, default: false) — Whether the requesting user dismissed the mention-invite prompt under this message. Always false for other users' messages and for unauthenticated reads.
- `agent_read_receipts` (list of AgentReadReceipt, optional, nullable) — Agent read receipts attached to the originating user message.

### ItemListMeta

- `total` (integer, required)
- `has_next` (boolean, required)
- `has_previous` (boolean, required)
- `page` (integer, required)
- `next_cursor` (string, optional, nullable)

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)
- `input` (any, optional)
- `ctx` (ValidationErrorCtx, optional)

### InteractionParticipant

The participant that sent this interaction.

### InteractionContentItems

### InvocationConfig

User-driven invocation configuration for a single turn. Every field is optional: producers only populate what the user actually selected, and readers apply their own per-twin/profile defaults when a field is `None`. In particular, `None` means "not specified" — for `enable_scheduled_prompt_tools` the reader default is *true*, so `None` must never be collapsed to `False`.

- `planner_mode` (boolean, optional, nullable)
- `athena_mode` (boolean, optional, nullable)
- `model_name` (string, optional, nullable)
- `mentions` (list of StructuredMention, optional, nullable)
- `withheld_mentions` (list of StructuredMention, optional, nullable)
- `private_mention_requests` (list of PrivateMentionRequestSchema, optional, nullable)
- `voice_mode` (boolean, optional, nullable)
- `voice_id` (string, optional, nullable)
- `enable_avatar` (boolean, optional, nullable)
- `character_id` (string, optional, nullable)
- `force_collaboration` (boolean, optional, nullable)
- `collaboration_participant_ids` (list of string, optional, nullable)
- `activity_id` (string, optional, nullable)
- `feed_activity_id` (string, optional, nullable)
- `use_reasoning_history` (boolean, optional, nullable)
- `thinking` (boolean, optional, nullable)
- `thinking_budget` (integer, optional, nullable)
- `reasoning_effort` (enum, optional, nullable)
  - Allowed values: `low`, `medium`, `high`
- `enable_web_search` (boolean, optional, nullable)
- `enable_study_mode` (boolean, optional, nullable)
- `enable_scheduled_prompt_tools` (boolean, optional, nullable)
- `avoid_repetition` (boolean, optional, nullable)
- `enable_threads` (boolean, optional, nullable)
- `slash_skills` (list of string, optional, nullable)
- `slash_only` (boolean, optional, nullable)
- `supports_tool_call_upsert` (boolean, optional, nullable)

### MessageReactionSummary

- `interaction_id` (string, required) — The interaction_id of the message.
- `emoji` (string, required) — Unicode emoji character for the reaction.
- `count` (integer, required) — Total number of reactors (users and agents) with this emoji.
- `reacted_by_me` (boolean, required) — Whether the current user has reacted with this emoji.
- `target_role` (enum, required) — Which message within the interaction this reaction targets.
  - Allowed values: `user`, `assistant`
- `reacted_by_agent` (boolean, optional, default: false) — Whether an agent authored this reaction.
- `reactor_names` (list of string, optional) — Display names of everyone who reacted, in reaction order, users before agents. Excludes the current user - clients render them from reacted_by_me - and reactors with no display name.
- `target_sender_id` (string, optional, nullable) — Author id of the targeted message; null for legacy reactions.

### AgentReadReceipt

- `id` (string, required)
- `message_event_id` (string, required)
- `interaction_id` (string, required)
- `agent_id` (string, required)
- `read_at` (string, required)

### ValidationErrorLocItems

### ValidationErrorCtx

### AuthenticatedUserParticipant

An authenticated user.

- `type` ("authenticated_user", required)
- `user_id` (string, required) — The ID of the authenticated user

### NonAuthenticatedUserParticipant

A non-authenticated user. This type can be used when providing a publicly available chatbot.

- `type` ("non_authenticated_user", required)
- `user_metadata` (map from string to string, optional, nullable) — Optional custom metadata about the user (such as IP address, browser, etc.) that may be useful for agents developers to identify usage of public chatbots. The platform doesn't use this metadata.

### MaybeUserParticipant

A user that might not yet exist in the system, identified by their email address.

- `type` ("maybe_user", required)
- `email` (string, required) — The email of the user.

### AgentParticipant

An AI agent that is registered with the platform.

- `type` ("agent", required)
- `agent_id` (string, required) — The ID of the agent
- `agent_metadata` (map from string to string, optional, nullable) — Metadata about the agent (such as name, avatar, address, etc.).
- `forwarded_for_agent` (ForwardedForAgentParticipant, optional, nullable) — Optional information about the agent that this participant forwarded the message for.

### ExternalAgentParticipant

An external AI agent (ie not registered with the platform).

- `type` ("external_agent", required)
- `agent_metadata` (map from string to string, optional, nullable) — Optional custom metadata about the agent (such as name, description, address, etc.).

### SystemParticipant

A system-level sender with no associated user or agent (e.g. channel notifications).

- `type` ("system", required)

### TextMessageContent

- `type` ("text", required)
- `text` (string, required)

### AudioTagContent

- `type` ("audio_tag", required)
- `tag` (string, required)

### MediaMessageContent

- `type` ("media", required)
- `meta_data` (MediaMetaData, required) — Describes the file a media packet delivers. ``name``, ``resource_type``, ``format`` and ``preview`` are optional: only agent-produced files set them, and a client that receives none of them falls back to the behaviour it had before they existed. ``preview`` is separate from ``description`` because ``description`` carries the filename.
- `media_url` (string, optional, nullable)

### CustomContent

- `type` ("custom_content", required)
- `name` (string, required)
- `version` (string, required)
- `data` (map from string to any, required)
- `alt_text` (string, optional, nullable)

### ToolCallContent

- `type` ("tool_call", required)
- `tool_name` (string, required)
- `tool_args` (map from string to any, required)
- `tool_call_id` (string, optional, nullable)
- `display_text` (string, optional, nullable) — User-facing text shown during tool execution (e.g., 'Searching the web...')

### ToolCallResultContent

- `type` ("tool_call_result", required)
- `tool_name` (string, required)
- `tool_result` (map from string to any, required)
- `tool_call_id` (string, optional, nullable)
- `status` (enum, optional, nullable)
  - Allowed values: `success`, `failure`, `rate_limited`, `action_required`
- `display_text` (string, optional, nullable) — User-facing text shown after tool completes (e.g., 'Found web results')

### ToolCallProgressContent

In-flight tool progress surfaced on refresh-shaped reads. Ephemeral: served from the windowed Redis store, never persisted, and only when the caller opts in.

- `type` ("tool_call_update", required)
- `tool_name` (string, required)
- `tool_call_id` (string, required)
- `sequence` (integer, required)
- `update` (ToolCallProgressContentUpdate, required)

### RequestPaymentContent

- `type` ("request_payment", required)
- `accepted_funds` (list of PaymentFunds, required)
- `recipient` (string, required)
- `deadline_seconds` (integer, required)
- `reference` (string, optional, nullable)
- `description` (string, optional, nullable)
- `metadata` (map from string to any, optional, nullable)

### CommitPaymentContent

- `type` ("commit_payment", required)
- `funds` (PaymentFunds, required)
- `recipient` (string, required)
- `transaction_id` (string, required)
- `reference` (string, optional, nullable)
- `description` (string, optional, nullable)
- `metadata` (map from string to any, optional, nullable)

### RejectPaymentContent

- `type` ("reject_payment", required)
- `reason` (string, optional, nullable)

### CompletePaymentContent

- `type` ("complete_payment", required)
- `transaction_id` (string, optional, nullable)

### CancelPaymentContent

- `type` ("cancel_payment", required)
- `transaction_id` (string, optional, nullable)
- `reason` (string, optional, nullable)

### StructuredMention

A single @mention with resolved metadata from the client. The client is the authority for mention data: it knows the exact entity the user selected from the autocomplete dropdown (type, ID, identifier). The backend validates and uses these IDs for routing instead of parsing message text with regular expressions.

- `type` (enum, required)
  - Allowed values: `agent`, `user`
- `id` (string, required)
- `identifier` (string, required)
- `identifier_type` (enum, required)
  - Allowed values: `handle`, `address`, `uuid`
- `offset` (integer, optional, nullable)
- `length` (integer, optional, nullable)

### PrivateMentionRequestSchema

Server-derived friend request a private-AI mention created (or found pending). A client renders the "request sent / already requested" prompt from this payload instead of a direct participant-add confirmation.

- `twin_id` (string, required)
- `outcome` (enum, required)
  - Allowed values: `private_friend_request`, `private_already_requested`
- `friendship_id` (string, required)
- `channel_id` (string, required)
- `owner_display_name` (string, optional, nullable)

### ForwardedForAgentParticipant

- `agent_address` (string, required)
- `agent_name` (string, required)
- `image_url` (string, optional, nullable)
- `agent_avatar_href` (string, optional, nullable, deprecated)

### MediaMetaData

Describes the file a media packet delivers. ``name``, ``resource_type``, ``format`` and ``preview`` are optional: only agent-produced files set them, and a client that receives none of them falls back to the behaviour it had before they existed. ``preview`` is separate from ``description`` because ``description`` carries the filename.

- `media_id` (string, required)
- `mime_type` (string, required)
- `width` (integer, required)
- `height` (integer, required)
- `description` (string, required)
- `source_url` (string, optional, nullable)
- `name` (string, optional, nullable)
- `resource_type` (string, optional, nullable)
- `format` (string, optional, nullable)
- `preview` (string, optional, nullable)

### ToolCallProgressContentUpdate

### PaymentFunds

- `amount` (string, required)
- `currency` (string, required)
- `payment_method` (string, optional, default: stripe)

### ToolCallUpdateStringContent

- `text` (string, required)
- `kind` ("string", optional)

### ToolCallUpdateChecklistContent

- `items` (list of ChecklistItem, required)
- `kind` ("checklist", optional)

### ChecklistItem

- `label` (string, required)
- `state` (enum, optional, default: pending)
  - Allowed values: `pending`, `active`, `done`

## Examples

**Response**

```json
{
  "items": [
    {
      "id": "foo",
      "created_at": "foo",
      "channel_id": "foo",
      "participant": {
        "type": "foo",
        "user_id": "foo"
      },
      "content": [
        {
          "type": "foo",
          "text": "foo"
        }
      ],
      "content_role": "user_message",
      "complete": true,
      "metadata": {},
      "invocation_config": {
        "planner_mode": true,
        "athena_mode": true,
        "model_name": "foo",
        "mentions": [
          {
            "type": "agent",
            "id": "foo",
            "identifier": "foo",
            "identifier_type": "handle",
            "offset": 42,
            "length": 42
          }
        ],
        "withheld_mentions": [
          {
            "type": "agent",
            "id": "foo",
            "identifier": "foo",
            "identifier_type": "handle",
            "offset": 42,
            "length": 42
          }
        ],
        "private_mention_requests": [
          {
            "twin_id": "foo",
            "outcome": "private_friend_request",
            "friendship_id": "foo",
            "channel_id": "foo",
            "owner_display_name": "foo"
          }
        ],
        "voice_mode": true,
        "voice_id": "foo",
        "enable_avatar": true,
        "character_id": "foo",
        "force_collaboration": true,
        "collaboration_participant_ids": [
          "foo"
        ],
        "activity_id": "foo",
        "feed_activity_id": "foo",
        "use_reasoning_history": true,
        "thinking": true,
        "thinking_budget": 42,
        "reasoning_effort": "low",
        "enable_web_search": true,
        "enable_study_mode": true,
        "enable_scheduled_prompt_tools": true,
        "avoid_repetition": true,
        "enable_threads": true,
        "slash_skills": [
          "foo"
        ],
        "slash_only": true,
        "supports_tool_call_upsert": true
      },
      "nested_interactions": [
        null
      ],
      "interaction_id": "foo",
      "sequence": 42,
      "span_id": "foo",
      "parent_span_id": "foo",
      "organization_id": "foo",
      "organization_application": "foo",
      "reactions": [
        {
          "interaction_id": "foo",
          "emoji": "foo",
          "count": 42,
          "reacted_by_me": true,
          "target_role": "user",
          "reacted_by_agent": false,
          "reactor_names": [
            "foo"
          ],
          "target_sender_id": "foo"
        }
      ],
      "mention_invite_prompt_dismissed": false,
      "agent_read_receipts": [
        {
          "id": "foo",
          "message_event_id": "foo",
          "interaction_id": "foo",
          "agent_id": "foo",
          "read_at": "foo"
        }
      ]
    }
  ],
  "meta": {
    "total": 42,
    "has_next": true,
    "has_previous": true,
    "page": 42,
    "next_cursor": "foo"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.flockx.io/api/v1/interactions"

querystring = {"end_time":"end_time"}

headers = {"Authorization": "<apiKey>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.flockx.io/api/v1/interactions?end_time=end_time';
const options = {method: 'GET', headers: {Authorization: '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.flockx.io/api/v1/interactions?end_time=end_time"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.flockx.io/api/v1/interactions?end_time=end_time")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.flockx.io/api/v1/interactions?end_time=end_time")
  .header("Authorization", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.flockx.io/api/v1/interactions?end_time=end_time', [
  'headers' => [
    'Authorization' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.flockx.io/api/v1/interactions?end_time=end_time");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.flockx.io/api/v1/interactions?end_time=end_time")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```