Skip to main content
GET
TypeScript SDK

Authorizations

Authorization
string
header
required

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

Query Parameters

agentId
string<uuid>

Filter sessions created by this automation agent.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
createdBy
string[]

Filter by creator IDs, supplied as a comma-separated list.

Minimum string length: 1
createdAfter
string<date-time>

Only sessions created after this ISO 8601 timestamp.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
cursor
string

Continuation cursor from the previous response nextCursor. Omit for the first page; null nextCursor means there are no more pages.

Maximum string length: 500
limit
integer
default:50

Maximum number of items to return in one page. Use nextCursor from the response to fetch more items.

Required range: 1 <= x <= 100
excludePinned
boolean

Exclude sessions pinned by the authenticated user.

excludeTeamId
string<uuid>

Exclude sessions shared with this team. Requires organization:team:read.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
externalIds
string[]

Filter by external source IDs, supplied as a comma-separated list.

Minimum string length: 1
folderId
string<uuid>

Only sessions in this sidebar folder of the authenticated user. Takes precedence over inFolder.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
hasProject
boolean

Filter by whether a session has an assigned project.

includeArchived
boolean
default:true

Include archived sessions in the all-state view. Defaults to true; state=archived explicitly selects archived sessions.

includeTotal
boolean
default:false

Include totalCount. Not supported with state=active.

inFolder
boolean

Filter by whether a session is in one of the authenticated user's sidebar folders.

parentSessionId
string<uuid>

Filter sessions created by this session.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
participant
string[]

Filter by participant IDs, supplied as a comma-separated list.

Minimum string length: 1
pendingReviewerKeys
string[]

Filter by pending reviewer keys, supplied as a comma-separated list.

Minimum string length: 1
projectIds
string[]

Filter by project IDs, supplied as a comma-separated list.

Minimum string length: 1
pullRequestStatuses
enum<string>[]

Filter by linked pull request statuses: open, merged, or closed, supplied as a comma-separated list.

Available options:
open,
merged,
closed
repositoryIds
string[]

Filter by repository IDs, supplied as a comma-separated list.

Minimum string length: 1

Search session titles, task prompts, kinds, and source names or types.

Required string length: 1 - 1000
sortBy
enum<string>
default:lastQueuedAt

Timestamp used to sort sessions, newest first.

Available options:
lastQueuedAt,
createdAt,
updatedAt
sourceIds
string[]

Filter by session source IDs, supplied as a comma-separated list.

Minimum string length: 1
sourceTypes
string[]

Filter by session source types, supplied as a comma-separated list.

Minimum string length: 1
state
enum<string>
default:all

Select all sessions, currently active work, or archived sessions. Use archived to find sessions to restore.

Available options:
all,
active,
archived
teamId
string<uuid>

Only sessions shared with this team. Requires organization:team:read.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Response

List sessions

items
object[]
required
nextCursor
string | null
required
totalCount
integer
Required range: 0 <= x <= 9007199254740991