List sessions

GET /api/v1/forward/sessions Lists sessions under the authenticated account in descending creation-time order by default. Archived sessions are excluded by default.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT or SAT>`

Query parameters

Parameter	Type	Required	Default	Description
`search`	string	No	-	Search query. Values beginning with `sess_` first match an exact Session ID; otherwise, the value is matched against titles. See Notes for matching rules.
`identity_ids`	string or array	No	-	Filter by one or more Identity IDs. Comma-separated strings are supported.
`template_id`	string	No	-	Filter by Forward Template ID.
`source_type`	string	No	-	Filter by `api`, `im`, `schedule`, or `batch`.
`created_at[gt]`	string	No	-	Created strictly after this RFC 3339 timestamp.
`created_at[gte]`	string	No	-	Created at or after this RFC 3339 timestamp.
`created_at[lt]`	string	No	-	Created strictly before this RFC 3339 timestamp.
`created_at[lte]`	string	No	-	Created at or before this RFC 3339 timestamp.
`updated_at[gt]`	string	No	-	Updated strictly after this RFC 3339 timestamp.
`updated_at[gte]`	string	No	-	Updated at or after this RFC 3339 timestamp.
`updated_at[lt]`	string	No	-	Updated strictly before this RFC 3339 timestamp.
`updated_at[lte]`	string	No	-	Updated at or before this RFC 3339 timestamp.
`limit`	integer	No	20	Items per page. Maximum 100.
`after_id`	string	No	-	Cursor for the next page. Pass the `last_id` from the previous response.
`before_id`	string	No	-	Cursor for the previous page. Pass the `first_id` from the current response.
`order`	string	No	`desc`	Creation-time sort order: `desc` or `asc`.
`include_archived`	boolean	No	`false`	Include archived sessions.

Example request

curl -s -X GET 'https://api.qoder.com.cn/api/v1/forward/sessions' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

Search by title keyword:

curl -s -X GET 'https://api.qoder.com.cn/api/v1/forward/sessions?search=support' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

Find a Session by ID:

curl -s -X GET 'https://api.qoder.com.cn/api/v1/forward/sessions?search=sess_xxx' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

Get the next page:

curl -s -X GET 'https://api.qoder.com.cn/api/v1/forward/sessions?limit=20&order=desc&after_id=sess_xxx' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

Example response

HTTP 200 OK

{
  "data": [
    {
      "id": "sess_xxx",
      "type": "session",
      "identity_id": "idn_xxx",
      "template": {
        "id": "tmpl_support",
        "type": "template",
        "name": "Support assistant",
        "model": "ultimate",
        "version": 3
      },
      "source_type": "im",
      "status": "idle",
      "title": "Customer support session",
      "metadata": {
        "source": "dingtalk"
      },
      "config": {
        "environment_variables": {
          "API_KEY": "sk-xxx"
        }
      },
      "resources": [
        {
          "id": "sesr_xxx",
          "type": "file",
          "file_id": "file_xxx",
          "mount_path": "/data/workspace/spec.md",
          "created_at": "2026-06-23T05:53:19Z",
          "updated_at": "2026-06-23T05:53:38Z"
        }
      ],
      "stats": {
        "active_seconds": 30,
        "duration_seconds": 3600
      },
      "usage": {
        "total_credits": 12.5
      },
      "archived_at": null,
      "created_at": "2026-06-22T10:00:00Z",
      "updated_at": "2026-06-22T11:00:00Z"
    }
  ],
  "first_id": "sess_xxx",
  "last_id": "sess_xxx",
  "has_more": false
}

Response fields

Field	Type	Description
`data`	array	Session objects on the current page.
`first_id`	string\|null	ID of the first record on this page.
`last_id`	string\|null	ID of the last record on this page.
`has_more`	boolean	Whether more records remain.

Errors

HTTP	Type	Code	Trigger
400	`invalid_request_error`	`invalid_time_range`	Time filters are invalid.
400	`invalid_request_error`	`invalid_time_filter`	The time-filter format is invalid.
400	`invalid_request_error`	`invalid_pagination`	Pagination parameters are invalid.
400	`invalid_request_error`	`invalid_limit`	`limit` is invalid or exceeds the maximum.
400	`invalid_request_error`	`invalid_order`	`order` is not `asc` or `desc`.
400	`invalid_request_error`	`invalid_search`	`search` is invalid UTF-8, exceeds 512 bytes, or contains control characters.
401	`authentication_error`	`authentication_required`	PAT or SAT invalid or expired.

Notes

search matching rules:

If the value begins with sess_, the API first attempts an exact Session ID match. A match returns only that Session; otherwise, the query falls back to title matching.
Title matching is a case-insensitive substring search. %, _, and \ are treated as literal characters.
Leading and trailing whitespace is removed. The remaining value must be valid UTF-8, no longer than 512 bytes, and contain no control characters.

Other notes:

after_id and before_id cannot be used together.
The list is sorted by created_at. Sessions with the same creation time are sorted by Session ID in the same direction to keep pagination stable.
Keep the same filters and order value when paging through results.
Current design does not support filtering by status.
usage.total_credits is returned only for newly created Sessions. Historical Sessions may omit it.
resources returns resources mounted in the session. It currently contains only file resources added through Add a session resource; it is an empty array when no resources are mounted.

Headers

Query parameters

Example request

Example response

Response fields

Errors

Notes

Create a session

Get a session

​Headers

​Query parameters

​Example request

​Example response

​Response fields

​Errors

​Notes

​Related

Create a session

Get a session

Headers

Query parameters

Example request

Example response

Response fields

Errors

Notes

Related