Ledga
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

NameInTypeDescription
Idempotency-Key header string
max length: 255

Request bodyrequired

FieldTypeDescription
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"
}'

← All endpoints