---
title: "documents.count"
method: POST
path: "/capabilities/documents.count"
tags: ["Capabilities"]
---

# documents.count

`POST /capabilities/documents.count`

Count documents and aggregate data. Use for spending totals and financial analysis. Supports grouping by merchant, category, date, export status, etc. Gets ALL matching documents.

## Request body

- object
  - `where` object — Typed filter clause. Allowed fields: id, amount, docDate, merchant, category, docType, invoiceId, receiptId, preferredCurrency, currency, paymentStatus, paymentMethod, paymentMethodEnding, fromEmail, toEmail, summary, expenseLocation.primary.countryCode, expenseLocation.primary.country, expenseLocation.primary.city, expenseLocation.primary.stateOrProvince, expenseLocation.primary.kind, taxAmount, subtotal, isRecurring, recurringType, entityId. Allowed ops: eq, ne, gt, gte, lt, lte, in, nin, regex, exists. Regex filters are already case-insensitive, so pass plain values like "grab" instead of inline flags like "(?i)grab".
    - `logic` 'and' | 'or'
    - `conditions` object[], required
      - `field` 'id' | 'amount' | 'docDate' | 'merchant' | 'category' | 'docType' | 'invoiceId' | 'receiptId' | 'preferredCurrency' | 'currency' | 'paymentStatus' | 'paymentMethod' | 'paymentMethodEnding' | 'fromEmail' | 'toEmail' | 'summary' | 'expenseLocation.primary.countryCode' | 'expenseLocation.primary.country' | 'expenseLocation.primary.city' | 'expenseLocation.primary.stateOrProvince' | 'expenseLocation.primary.kind' | 'taxAmount' | 'subtotal' | 'isRecurring' | 'recurringType' | 'entityId', required
      - `op` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'regex' | 'exists', required
      - `value` unknown
  - `exportStatus` 'all' | 'exported' | 'not-exported' — Optional export status filter before aggregation
  - `archived` 'exclude' | 'only' | 'include' — Archive filter: exclude (default, active docs), only (archived docs), include (both).
  - `groupBy` 'merchant' | 'category' | 'docType' | 'currency' | 'preferredCurrency' | 'paymentMethod' | 'paymentMethodEnding' | 'paymentStatus' | 'entityId' | 'docDate' | 'expenseLocation.primary.countryCode' | 'expenseLocation.primary.country' | 'expenseLocation.primary.city' | 'expenseLocation.primary.stateOrProvince' | 'expenseLocation.primary.kind' | 'exportStatus' — Aggregation key. Allowed values: merchant, category, docType, currency, preferredCurrency, paymentMethod, paymentMethodEnding, paymentStatus, entityId, docDate, expenseLocation.primary.countryCode, expenseLocation.primary.country, expenseLocation.primary.city, expenseLocation.primary.stateOrProvince, expenseLocation.primary.kind, exportStatus. Use exportStatus to summarize exported vs not-exported documents.

## Response `200`

Successful response

- object
  - `success` boolean
  - `code` integer
  - `data` object
    - `result` object — Capability-specific result

## Other responses

- `400` — Invalid input
- `401` — Authentication required
- `404` — Resource not found

---

[API](https://skmtc.net/receiptor/apis/receiptor-ai-api.md) · [All operations](https://skmtc.net/receiptor/apis/receiptor-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/receiptor/receiptor-ai-api/versions/da17f0eb65a2/schema)