POST
/transactions/search/export Export the transactions a filter matches
Exports a report specification v2 (version, filter, columns, sort), with format and an optional idempotency_key (or Idempotency-Key header); limit and cursor are refused. It holds the transactions as of the request, relative dates resolved to the ledger's current day, the columns in order (attribute columns included) and a totals row. Poll GET /api/v1/exports/{export} until completed, then download. The same key on this ledger, with the same body, returns that export with meta.replayed: true; otherwise it is refused on idempotency_key.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string max length: 255 |
Request bodyrequired
| Field | Type | Description |
|---|---|---|
versionrequired | integer enum: 2 | |
filter | ReportFilter | Which transactions match the report specification v2; every member present must match. Absent or {}: every transaction created in the last 30 days. |
filter.created_at | ReportWindow | An inclusive window: a preset, or both bounds as local days (YYYY-MM-DD, in the ledger's timezone) or as ISO 8601 instants with an offset or Z. At most 12 months. |
filter.effective_date | ReportWindow | An inclusive window: a preset, or both bounds as local days (YYYY-MM-DD, in the ledger's timezone) or as ISO 8601 instants with an offset or Z. At most 12 months. |
filter.amount | object | Bounds on the stored total in major units: a non-negative integer, or a decimal string such as "100.00"; once the ledger's stored totals are verified |
filter.status | string[] min items: 1 | |
filter.layer | string[] min items: 1 | |
filter.any_of | ReportAttributeGroup[] min items: 1 · max items: 5 | Groups, ORed; at most 250 in values over the whole filter |
filter.account_id | string uuid | |
filter.account_set_id | string uuid | |
filter.transaction_code_id | string uuid | |
filter.journal_id | string uuid | |
filter.correlation_id | string min length: 1 · max length: 50 | Only the transactions with this correlation handle: those given this correlation_id, and the one with this id that was given none. Valid UTF-8, no NUL, and not whitespace alone |
filter.text | string min length: 3 · max length: 100 | A prefix of the reference, external id or correlation id, or a part of the description; at least three letters or digits |
filter.is_reversal | boolean | |
filter.has_reversal | boolean | |
filter.is_voided | boolean | |
columns | string[] min items: 1 · max items: 30 | As the search's: the file's columns, in their order |
sort | object | |
sort.byrequired | string enum: created_at | effective_date | amount | |
sort.directionrequired | string enum: desc | asc | |
formatrequired | string enum: csv | xlsx | |
idempotency_key | string max length: 255 · nullable |
Responses
200A replay of an idempotency key: the export it started, with meta.replayed: true
{
"success": true,
"meta": {
"replayed": true
},
"data": {
"id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"export_type": "transactions",
"format": "csv",
"status": "pending",
"as_of": null,
"start_date": null,
"end_date": null,
"definition": null,
"row_count": null,
"file_size": null,
"error_message": null,
"download_url": null,
"created_at": "2026-01-15T10:30:00Z",
"completed_at": null,
"failed_at": null
}
} 202The export, started
{
"success": true,
"meta": {
"replayed": true
},
"data": {
"id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"export_type": "transactions",
"format": "csv",
"status": "pending",
"as_of": null,
"start_date": null,
"end_date": null,
"definition": null,
"row_count": null,
"file_size": null,
"error_message": null,
"download_url": null,
"created_at": "2026-01-15T10:30:00Z",
"completed_at": null,
"failed_at": null
}
} 401Unauthenticated
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} 403Forbidden (no ledger context)
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} 409EXPORTS_IN_PROGRESS: the ledger, or this key, has as many exports in progress as it may
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} 422A specification outside the rules, as for the search; INVALID_REFERENCE, AMOUNT_NOT_READY or SEARCH_NOT_READY as for the search; a format other than CSV or XLSX, or an idempotency key used for another export
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} 429The export limit
{
"success": false,
"message": "Validation failed",
"code": "VALIDATION_ERROR"
} Examples
curl -X POST https://ledga.io/api/v1/transactions/search/export \
-H "Authorization: Bearer sk_xxxxxxxx_your_secret" \
-H "Content-Type: application/json" \
-d '{
"version": 2,
"filter": {
"created_at": {
"preset": "today"
},
"effective_date": {
"preset": "today"
},
"amount": {
"min": "string",
"max": "string"
},
"status": [
"posted"
],
"layer": [
"settled"
],
"any_of": [
{
"all_of": [
{
"key": "customer_id",
"op": "eq",
"value": "string",
"values": [
"string"
]
}
]
}
],
"account_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"account_set_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"transaction_code_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"journal_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"correlation_id": "01997c1e-4d2a-7c3e-9a1b-2f0e8c6d4b5a",
"text": "string",
"is_reversal": true,
"has_reversal": true,
"is_voided": true
},
"columns": [
"string"
],
"sort": {
"by": "created_at",
"direction": "desc"
},
"format": "csv"
}'