Skip to main content
GET
/
api
/
v1
/
skills
/
{id}
/
conversations
List conversations for a skill scope
curl --request GET \
  --url https://api.staging.getmodus.com/api/v1/skills/{id}/conversations \
  --header 'Authorization: Bearer <token>'
{
  "conversations": [
    {
      "threadId": "agent_42_abc-xyz",
      "skillId": 42,
      "firstMessage": "Run the churn analysis for last 30 days.",
      "title": "Q3 Revenue Analysis",
      "messageCount": 12,
      "createdAt": "2026-05-01T10:00:00.000Z",
      "updatedAt": "2026-05-01T11:00:00.000Z",
      "userIds": [
        "user_abc"
      ],
      "toolsUsed": [
        "sql_runner"
      ]
    }
  ],
  "nextPageToken": "eyJwYWdlIjoxLCJwYWdlU2l6ZSI6MTB9",
  "totalCount": 47,
  "page": 0,
  "pageSize": 10
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
id
number
required

Numeric skill scope. Use 0 for cross-skill recent history.

Example:

42

Query Parameters

​
pageToken
string

Opaque page token from a previous response's nextPageToken. Omit for the first page. AIP-158.

Example:

"eyJwYWdlIjoxLCJwYWdlU2l6ZSI6MjV9"

​
page
number

Legacy zero-indexed page number. Defaults to 0. Prefer pageToken; if both are supplied, pageToken wins.

Required range: x >= 0
Example:

0

​
pageSize
number

Items per page. Defaults to 10, clamped to 100.

Required range: 1 <= x <= 100
Example:

10

​
userId
string

Filter by user id who participated in the conversation. Exact match against the conversation_interactions.user_id column.

Example:

"user_abc"

​
toolName
string

Filter by tool name invoked in the conversation. Applied post-fetch (requires reading message blobs); use includeTools=true to also see the matched tools.

Example:

"sql_runner"

​
timeframe
enum<string>

Filter by activity recency. Coarse server-side buckets.

Available options:
last_day,
this_week,
this_month,
last_7_days,
last_30_days
Example:

"last_7_days"

​
includeTools
boolean

When true, populate toolsUsed on each list item by scanning message blobs. Defaults to false to keep the list cheap.

Example:

false

Response

​
conversations
object[]
required

Page of conversation summaries, newest-updated first.

​
nextPageToken
string | null
required

Opaque token for the next page. null when there are no further pages. AIP-158.

Example:

"eyJwYWdlIjoxLCJwYWdlU2l6ZSI6MTB9"

​
totalCount
number
required

Total threads visible in the scanned window after filters. Not a global count.

Example:

47

​
page
number

Legacy echo of the requested 0-indexed page. Retained for SPA backwards-compatibility; new callers should rely on pageToken / nextPageToken.

Example:

0

​
pageSize
number

Legacy echo of the requested pageSize. Retained for SPA backwards-compatibility.

Example:

10