List Files

List files with optional filtering and pagination.

Filter by file_name, file_ids, or external_file_id. Supports cursor-based pagination and custom ordering.

get/api/v1/beta/files

Query parameters

page_sizeinteger nullable

The maximum number of items to return. Defaults to 50, maximum is 1000.

page_tokenstring nullable

A page token received from a previous list call. Provide this to retrieve the subsequent page.

file_idsstring[] nullable

Filter by specific file IDs.

file_namestring nullable

Filter by file name (exact match).

external_file_idstring nullable

Filter by external file ID.

order_bystring nullable

A comma-separated list of fields to order by, sorted in ascending order. Use 'field_name desc' to specify descending order.

expandstring[] nullable

Fields to expand on each file.

project_idstring uuid nullable

organization_idstring uuid nullable

Cookies

sessionstring nullable

Response

Successful Response

next_page_tokenstring nullable

A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.

total_sizeinteger nullable

The total number of items available. This is only populated when specifically requested. The value may be an estimate and can be used for display purposes only.

Example response

{
  "items": [
    {
      "id": "dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "name": "invoice.pdf",
      "external_file_id": "ext-12345",
      "file_type": "pdf",
      "project_id": "123e4567-e89b-12d3-a456-426614174000",
      "purpose": "parse"
    }
  ]
}

Changes

Changed in 7 of the 33 revisions of this API.49

Jun 9, 2026b17341164de92See the full diff
- ○
  added the optional property detail/items/ctx to the response with the 422 status
  response-optional-property-added
- ○
  added the optional property detail/items/input to the response with the 422 status
  response-optional-property-added
This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
May 23, 202634da5826db1c2See the full diff
- ○
  added the new optional query request parameter expand
  new-optional-request-parameter
- ○
  added the optional property items/items/download_url to the response with the 200 status
  response-optional-property-added
May 21, 2026fb63fb8d662c2See the full diff
- ●
  deleted the query request parameter expand
  request-parameter-removed
- ●
  removed the optional property items/items/download_url from the response with the 200 status
  response-optional-property-removed
This revision also has 46 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
May 16, 2026c317ed7c691a2See the full diff
- ○
  added the new optional query request parameter expand
  new-optional-request-parameter
- ○
  added the optional property items/items/download_url to the response with the 200 status
  response-optional-property-added
May 14, 20261bbc901f8c0d2See the full diff
- ●
  deleted the query request parameter expand
  request-parameter-removed
- ●
  removed the optional property items/items/download_url from the response with the 200 status
  response-optional-property-removed
This revision also has 6 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
May 12, 2026548a0c57fdd62See the full diff
- ○
  added the new optional query request parameter expand
  new-optional-request-parameter
- ○
  added the optional property items/items/download_url to the response with the 200 status
  response-optional-property-added
Apr 24, 20261bbc901f8c0d1See the full diff
- ○
  api tag Files added
  api-tag-added
This revision also has 9 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history