---
title: "List documents."
method: GET
path: "/documents"
tags: ["Documents"]
---

# List documents.

`GET /documents`

## Request

- Base URL: `https://h2ogpte.genai.h2o.ai/api/v1`
- URL: `https://h2ogpte.genai.h2o.ai/api/v1/documents`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/h2o/apis/h2ogpte-rest-api/docs/documents/get.ts> (a function with typed inputs; its response is checked against the schema)

List documents for a given user. If sort_column is not specified, the output is sorted by by last update time in descending order.

## Query parameters

- `offset` integer
- `limit` integer
- `sort_column` 'name' | 'username' | 'type' | 'size' | 'page_count' | 'connector' | 'uri' | 'original_type' | 'original_mtime' | 'status' | 'updated_at'
- `ascending` boolean
- `with_summaries` boolean
- `metadata_filter` string
- `username` string
- `status` string
- `source` string
- `chat_session_id` string
- `group_by_source_chat` boolean

## Response `200`

Successful operation

- Document[]
  - `id` string, required: A unique identifier of the document
  - `name` string, required: Name of the document
  - `username` string, required: A username owning the document
  - `type` string, required: Type of the document
  - `size` integer, required: Size of the document in bytes
  - `page_count` integer, required: A number of pages contained in the document
  - `status` 'unknown' | 'scheduled' | 'queued' | 'running' | 'completed' | 'failed' | 'canceled' | 'agent_only', required: Status of the document
  - `usage_stats` string: Usage stats
  - `connector` string
  - `original_type` string
  - `original_mtime` string, datetime
  - `created_at` string, date-time, required: Time when document was created
  - `updated_at` string, date-time, required: Last time when document was modified
  - `uri` string
  - `summary` string
  - `summary_parameters` string
  - `metadata_dict` Metadata
  - `is_encrypted` boolean: Whether the document files are encrypted at rest
  - `chat_session_id` string: A unique identifier of the chat session that generated the document. Returned by GET /documents. Only set for agent-generated files, null for user-uploaded documents.
  - `chat_session_name` string: Name of the chat session that generated the document. Returned by GET /documents. Null when the document was not generated by an agent, or when the session is not visible to the caller.
  - `chat_session_visible` boolean: Whether the caller can open the chat session that generated the document. Returned by GET /documents. Distinct from chat_session_name being null, which also happens when a visible session has no name yet.

## Other responses

- `400`: Bad request
- `401`: Unauthorized - Invalid or missing API key
- `default`: Unexpected error

---

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