---
title: "Count documents by type"
method: GET
path: "/api/v1/rest/documents/facets"
tags: ["Documents"]
---

# Count documents by type

`GET /api/v1/rest/documents/facets`

## Request

- Base URL: `https://api.custodo.ai`
- URL: `https://api.custodo.ai/api/v1/rest/documents/facets`
- Auth: HTTP bearer

Faceted counts over the archive — how many documents fall under each type, plus an optional second count bucketed by type, status or direction. Answers "how many" without paging through documents_search to count rows yourself: it takes the SAME filters, so call this first to see the shape of an answer before deciding whether to list the documents behind it. The per-type counts ignore the `type` filter itself, so «quante fatture in entrata» stays visible even while another type is already selected. A count stops at 1000: `count_capped: true` means 1000 OR MORE — say so, never report it as an exact number.

**Examples**

- How many invoices do we have per status?
  `GET /api/v1/rest/documents/facets?type=fattura_entrata&group=status`
- How many documents are still being processed right now?
  `GET /api/v1/rest/documents/facets?status=extracting`

## Query parameters

- `query` string
- `type` string
- `direction` 'in_entrata' | 'in_uscita'
- `status` 'pending' | 'converting' | 'extracting' | 'indexing' | 'ready' | 'failed'
- `from` string
- `to` string
- `group` 'title' | 'labels' | 'version' | 'party' | 'area' | 'type' | 'status' | 'direction' | 'extension' | 'size' | 'pages' | 'created'

## Headers

- `X-Tenant-Id` string, uuid

## Response `200`

Done. `data` is the tool’s own answer.

- RestResult
  - `ok` true, required
  - `data` unknown, required

## Other responses

- `400`: The arguments did not validate: `error.message` names the field, what it expects and what arrived.
- `401`: No API key, or one that is malformed, unknown, revoked or expired.
- `403`: The call never ran: the module is off for this organisation, the credential lacks the permission or the module, the tier does not cover it, or the tool is destructive and the key was not minted for that.
- `422`: The tool ran and refused, in a sentence of its own (`TOOL_REFUSED`): the message says what to change. Retrying the same call will not help.
- `429`: The API key has spent its minute, or its day. Every request a key makes counts. See `Retry-After`.

---

[API](https://skmtc.dev/custodo/apis/custodo-integrazioni.md) · [All operations](https://skmtc.dev/custodo/apis/custodo-integrazioni/llms.txt) · [OpenAPI document](https://skmtc.dev/custodo/apis/custodo-integrazioni/revisions/16d336d3ec2a?raw)