List conversations

Returns a paginated list of conversations, newest first. Rich filter surface lets you search by ticket ID, metadata, date range, model, title keyword, and source.

Scope: conversations:read

Default behavior

By default every conversation is visible except sub-agent runs, which are excluded because they'd dominate the list for any org running multi-agent workflows. To see sub-agent runs, pass source=sub-agent explicitly.

Query parameters

Pagination

Param	Type	Default	Notes
cursor	string		Opaque token from a previous response's meta.next_cursor.
limit	integer	25	Range 1–100.

Resource filters

Param	Type	Notes
agent_id	string	Filter to one agent. Accepts agent_<24 hex> or a bare ObjectId.
source	enum	dashboard | autonomous | embed | sub-agent. Sub-agent runs only appear when explicitly requested.
model	string	Exact match against the model used (e.g. gpt-5-mini).
parent_conversation_id	string	Filter to sub-agent runs of one parent conversation.
conversation_number	integer	Exact match against the per-org sequence number. ?conversation_number=42 fetches conversation #42.

Date filters

Param	Type	Notes
since	ISO 8601	last_message_at >= since. Back-compat alias for last_message_after.
created_after / created_before	ISO 8601	Half-open range on created_at.
last_message_after / last_message_before	ISO 8601	Half-open range on last_message_at.

Metadata + search

Param	Type	Notes
ticket_id	string or integer	Shorthand. Matches metadata.ticketId, metadata.ticket_id, OR triggerPayload.ticket.id. Both string and numeric storage forms checked.
metadata[KEY]	string	Match against the Mixed metadata field by bracket notation: ?metadata[priority]=high&metadata[region]=apac. String and numeric forms tried; "true"/"false" also coerced to boolean. Keys with $ or . are silently dropped to prevent operator injection.
q	string	Case-insensitive regex search against title only. Special regex characters escaped, paste search terms verbatim.

Examples

Find conversations about ticket 12345

curl 'https://dashboard.getmacha.com/api/v1/conversations?ticket_id=12345' \
  -H "Authorization: Bearer $MACHA_API_KEY"

Autonomous conversations from last week using gpt-5-mini

curl 'https://dashboard.getmacha.com/api/v1/conversations?source=autonomous&model=gpt-5-mini&created_after=2026-06-17T00:00:00Z' \
  -H "Authorization: Bearer $MACHA_API_KEY"

Sub-agent runs of one parent

curl 'https://dashboard.getmacha.com/api/v1/conversations?source=sub-agent&parent_conversation_id=conv_6a28f567ba502f55d177bb50' \
  -H "Authorization: Bearer $MACHA_API_KEY"

Conversations tagged with custom metadata

curl 'https://dashboard.getmacha.com/api/v1/conversations?metadata%5Bpriority%5D=high&metadata%5Bregion%5D=apac' \
  -H "Authorization: Bearer $MACHA_API_KEY"

Example response

{
  "data": [
    {
      "id": "conv_6a392325b438d825ccaf0dc1",
      "title": "process ticket 549",
      "source": "autonomous",
      "agent_id": "agent_6a28e310f2ec711ef6dc1dcf",
      "model": "gpt-5",
      "autonomous": true,
      "is_onboarding": false,
      "is_simulation": false,
      "conversation_number": 225,
      "parent_conversation_id": null,
      "credits_used": 3,
      "metadata": { "ticketId": 549 },
      "message_count": null,
      "last_message_at": "2026-06-10T05:26:55.455Z",
      "created_at": "2026-06-10T05:25:59.447Z",
      "updated_at": "2026-06-10T05:26:56.048Z"
    }
  ],
  "meta": {
    "request_id": "req_...",
    "next_cursor": "conv_6a28f567ba502f55d177bb50"
  }
}

Errors

Status	Code	When
401	unauthorized	Missing / invalid / revoked key.
403	insufficient_scope	Key lacks conversations:read.
422	validation_failed	Bad date format, unknown source value, malformed cursor, etc.
429	rate_limited	Per-key ceiling exceeded.