Skip to main content

List Documents

List every document in your Talonic workspace with GET /v1/documents. Filter by source, status, or date range, search filenames, and paginate with cursors.

The List Documents endpoint, GET /v1/documents, returns every document in your Talonic workspace: files uploaded directly, submitted through the API, or pulled in by a source connector. Each document record carries the original file metadata, its processing status, and links to its extractions. Use it to browse your document inventory, monitor processing, or drive cleanup workflows.

Use query parameters to filter by source connection, source type, processing status, or date range, or to run a case-insensitive filename search. Results are paginated with cursor-based navigation.

Documents include triage metadata (sensitivity, department, jurisdiction, PII detection) when available. Triage is populated automatically during ingestion via Document AI annotations or Haiku LLM calls.
GET/v1/documents

Query parameters

source_idstringFilter by source connection ID.
source_typestringFilter by source type (e.g. api, manual).
statusstringFilter by status: pending, processing, completed, error.
afterstringISO 8601 datetime. Only documents created after this timestamp.
beforestringISO 8601 datetime. Only documents created before this timestamp.
searchstringCase-insensitive filename search.
limitintegerMaximum number of results to return (1–100). Default: 20
cursorstringPagination cursor from a previous response.
orderstringSort direction by created_at. Default: desc

curl

curl -s "https://api.talonic.com/v1/documents?limit=10&status=completed" \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

Response fields

dataarrayArray of document objects.
data[].idstringDocument UUID.
data[].filenamestringOriginal filename of the uploaded document.
data[].pagesintegerEstimated page count.
data[].size_bytesintegerFile size in bytes.
data[].mime_typestringMIME type of the original file.
data[].type_detectedstring | nullDocument type inferred during processing (e.g. invoice, contract).
data[].language_detectedstring | nullISO 639-1 language code detected during extraction.
data[].statusstringProcessing status: pending, processing, completed, error.
data[].errorstring | nullError message when status is error.
data[].sourceobjectSource information: id (source connection ID or null) and type (e.g. manual, google_drive).
data[].triageobject | nullTriage metadata: sensitivity, department, jurisdiction, pii_detected, pii_categories, regulated_data, confidentiality_marking.
data[].original_pathstring | nullOriginal file path if ingested via a connector.
data[].extraction_countintegerNumber of extractions performed on this document (0 or 1).
data[].latest_extraction_idstring | nullID of the most recent extraction, if any.
data[].created_atstringISO 8601 creation timestamp.
data[].linksobjectRelated resource URLs: self, extractions, dashboard.
pagination.totalintegerTotal number of documents matching the query.
pagination.limitintegerMaximum results per page.
pagination.has_morebooleanWhether more results exist beyond this page.
pagination.next_cursorstring | nullCursor to fetch the next page. Null if no more results.

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "filename": "invoice-0847.pdf",
      "pages": 2,
      "size_bytes": 184320,
      "mime_type": "application/pdf",
      "type_detected": "invoice",
      "language_detected": "en",
      "status": "completed",
      "error": null,
      "source": {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "type": "manual"
      },
      "triage": {
        "sensitivity": "internal",
        "department": "finance",
        "jurisdiction": "EU",
        "pii_detected": false,
        "pii_categories": [],
        "regulated_data": false,
        "confidentiality_marking": null
      },
      "original_path": null,
      "extraction_count": 1,
      "latest_extraction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2024-09-14T10:32:00.000Z",
      "links": {
        "self": "/v1/documents/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "extractions": "/v1/documents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/extractions",
        "dashboard": "https://app.talonic.com/documents/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  ],
  "pagination": {
    "total": 234,
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJpZCI6ImExYjJjM2Q0IiwiY3JlYXRlZEF0IjoiMjAyNC0wOS0xNFQxMDozMjowMFoifQ=="
  }
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

How do I list documents in Talonic?+
Send a GET request to https://api.talonic.com/v1/documents with your API key in the Authorization header. Optional query parameters filter by source, status, date range, or filename search, and results are paginated with a cursor.
What document statuses are possible?+
Documents progress through pending (uploaded, awaiting processing), processing (OCR and extraction in progress), completed (ready for use), or error (processing failed). Filter on any of these with the status query parameter.
How does the search parameter work?+
The search parameter performs a case-insensitive match against document filenames. To find documents by their extracted content or field values instead, use the extraction and fields endpoints.
How do I page through large document lists?+
Pass limit (1 to 100, default 20) and follow pagination.next_cursor from each response as the cursor parameter of the next request. When has_more is false you have reached the end.

Related

Get Document
List Extractions
Convert a File to Markdown
List Sources