---
title: "List Artifacts"
method: GET
path: "/v2/artifacts"
tags: ["artifacts"]
---

# List Artifacts

`GET /v2/artifacts`

## Request

- Base URL: `https://api.getauctor.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getauctor.com/v2/artifacts`
- Auth: none declared

List the sessions, documents, diagrams, and folders in a space, newest first. Set `recursive=true` to include the spaces under it, and `type` to list one kind of artifact.

Results are paged by cursor. Each response has `data` and `next_cursor`. To get the next page, send `next_cursor` back as `cursor` with the same `space`, `type`, and `recursive`. Stop when `next_cursor` is `null`. There is no total count, and `offset` is not supported: a request with `offset` greater than 0 returns `400`. A page can hold fewer than `limit` items, even none, while `next_cursor` is still set. This happens when a request checks its maximum number of files without filling the page, so keep paging until `next_cursor` is `null`. A cursor is only valid for the listing it came from. Any other cursor returns `400`.

Documents, diagrams, and folders are listed only if the API key's user can open them in Auctor, including files shared to them through restrictions and grants. Files the user can't open are left out of `data` and never take a place on a page. Sessions are not filtered by file role. An M2M token has no user, so it lists only files with no restriction on themselves or on any folder above them.

These file-role checks apply only once file permissions are turned on for your organization. Until then, the list includes every document, diagram, and folder in the space.

Returns `503` if file roles can't be read. Retry the request.

## Query parameters

- `space` string, required
- `recursive` boolean
- `type` 'session' | 'document' | 'diagram' | 'folder', nullable
- `limit` integer
- `cursor` string, nullable: `next_cursor` from the previous page

## Response `200`

Successful Response

- ArtifactsListResponse
  - `data` ArtifactListItem[], required
    - `id` string, required
    - `type` 'session' | 'document' | 'diagram' | 'folder', required
    - `name` string, required
    - `space_id` string, required
    - `folder_ids` string[]
    - `created_at` string, required
    - `last_content_updated_at` string, nullable: Last time the document or diagram content itself changed; unchanged by renames and moves. Null for sessions.
    - `external_ids` object
  - `next_cursor` string, nullable, required: Pass as `cursor` to fetch the next page; null when the listing is exhausted.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-15** `ac6604419675`: 1 breaking, 1 warning, 2 info
  - removed the required property `total` from the response with the `200` status
  - deleted the `query` request parameter `offset`
  - added the new optional `query` request parameter `cursor`
  - added the required property `next_cursor` to the response with the `200` status
- **2026-09-01** `aeb6faa3b8f0`: 1 info
  - added the optional property `data/items/last_content_updated_at` to the response with the `200` status

[Operation history](https://skmtc.dev/getauctor/apis/getauctor-api/changes/v2/artifacts/get.md)

---

[API](https://skmtc.dev/getauctor/apis/getauctor-api.md) - [All operations](https://skmtc.dev/getauctor/apis/getauctor-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getauctor/apis/getauctor-api/revisions/be39c59c13f6?raw)