# List chat artifact refs

List the chat artifacts the authenticated user has created — documents, presentations, spreadsheets, and dashboards spawned through chat. Results are newest-first by creation time. Filter by artifact type or by the chat thread the artifact was created in. Soft-deleted refs are excluded by default. Pagination is opaque-cursor — pass the previous response's `next_cursor` as the `cursor` query parameter to fetch the next page.

A `thread_id` listing also returns artifacts **other members created in that chat**, when the caller can read the chat itself or already has access to the artifact. Sharing a chat shares the documents in it, so the chat's document list shows them.

## Query parameters

**`type`** string optional

Filter by artifact kind. One of `document`, `presentation`, `spreadsheet`, `dashboard`. Omit to include every type.

**`thread_id`** string optional

Filter to artifacts created in a specific chat thread. Paginates the same way as an unfiltered listing — pass `cursor` to walk past the first `limit` rows.

**`active_only`** boolean optional

When `true` (the default), excludes soft-deleted refs. Set to `false` to include them for audit or history views.

**`cursor`** string optional

Opaque pagination cursor returned as `next_cursor` by the previous page. Omit to fetch the first page.

**`limit`** integer optional

Page size — between 1 and 100. Default 50.

## Returns

Returns a `ChatArtifactRefListResponse` object containing an array of `ChatArtifactRef` rows in newest-first order and an opaque `next_cursor` for pagination.

Request

```bash cURL
curl -X GET "https://api.aitronos.com/v1/chat-artifacts/refs?limit=20" \
  -H "X-API-Key: $FREDDY_API_KEY"
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")
result = client.chat_artifacts.refs.list(limit=20)
for ref in result.refs:
    print(f"{ref.id} ({ref.smoc_entity_type}): {ref.title_snapshot}")
```


```python Python
import os, requests

response = requests.get(
    "https://api.aitronos.com/v1/chat-artifacts/refs",
    params={"limit": 20},
    headers={"X-API-Key": os.environ["FREDDY_API_KEY"]},
)
print(response.json())
```


```javascript JavaScript
const url = new URL("https://api.aitronos.com/v1/chat-artifacts/refs");
url.searchParams.set("limit", "20");
const response = await fetch(url, {
  headers: { "X-API-Key": process.env.FREDDY_API_KEY },
});
console.log(await response.json());
```

Response

```json
{
  "refs": [
    {
      "id": "carfref_aaaa1111bbbb2222cccc3333dddd4444",
      "organization_id": "org_abc",
      "created_by_user_id": "usr_abc",
      "smoc_entity_type": "document",
      "smoc_entity_id": "itm_revenue_plan",
      "created_in_thread_id": "thread_qwerty",
      "created_in_message_id": "msg_abcd1234",
      "title_snapshot": "Q1 Revenue Plan",
      "title_snapshot_at": "2026-04-19T14:00:00Z",
      "last_opened_at": "2026-04-19T15:22:11Z",
      "created_at": "2026-04-19T14:00:00Z",
      "deleted_at": null
    }
  ],
  "next_cursor": null
}
```

Error

```json
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required",
    "system_message": "Authentication required",
    "type": "authentication_error",
    "status": 401,
    "details": {},
    "trace_id": "...",
    "timestamp": "..."
  }
}
```

## Related Resources

- [Retrieve a chat artifact ref](/docs/api-reference/chat-artifacts/get-ref)
- [Delete a chat artifact ref](/docs/api-reference/chat-artifacts/delete-ref)