List Transactions

get/v1/transactions

Returns a cursor-paginated list of transactions for the active workspace. Read only, no side effects. Results are scoped by workspace via row-level security; for example a Stripe payout settling into Foldspace AI's Mercury account. Attributes mirror the records field set for this root. ## Filtering & sorting Filter via `POST /v1/records/query` (root `transactions`) or the `filters` model; operators are gated by each field's data type. See [Filtering & sorting](../filtering-and-sorting). **Filterable fields** | Field | Type | Allowed operators | |---|---|---| | `booking_date` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `category_confidence` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `category_normalized` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `category_purpose` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `category_source` | enum | `eq` `neq` `in` `is_null` `is_not_null` | | `composite_amount` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_category` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_fx_rate` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_instructed_amount_currency` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_invoice_transactions_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_invoices_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_journal_entries_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_routed_to` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_settlement_variance` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_sourced_from` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_transaction_documents_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_transaction_from` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_transaction_to` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `created_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `deleted_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `executed_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `ledger_account_role` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `object` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `pk` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `purpose_code` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `requested_execution_date` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `scheme` | enum | `eq` `neq` `in` `is_null` `is_not_null` | | `status` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `transaction_external_id` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `transaction_id` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `type` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `updated_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `value_date` | date | `eq` `lt` `gt` `is_null` `is_not_null` | **Sortable fields:** `booking_date`, `category_confidence`, `category_normalized`, `category_purpose`, `category_source`, `composite_amount`, `composite_category`, `composite_fx_rate`, `composite_instructed_amount_currency`, `composite_invoice_transactions_list`, `composite_invoices_list`, `composite_journal_entries_list`, `composite_routed_to`, `composite_settlement_variance`, `composite_sourced_from`, `composite_transaction_documents_list`, `composite_transaction_from`, `composite_transaction_to`, `created_at`, `deleted_at`, `executed_at`, `ledger_account_role`, `object`, `pk`, `purpose_code`, `requested_execution_date`, `scheme`, `status`, `transaction_external_id`, `transaction_id`, `type`, `updated_at`, `value_date` (via `orderBy` / `sort`, `asc`|`desc`).

Requires a bearer token: Authorization: Bearer <token>.

Query parameters

NameTypeRequiredDescription
cursorstringNoOpaque pagination cursor returned as links.next on the previous page. Omit to fetch the first page.e.g. eyJwayI6MTI4N30
limitintegerNoMaximum number of records to return per page (1 to 200, defaults to 50).e.g. 50
orderBystringNoField to sort by, using the records dot path or column name (e.g. created_at).e.g. created_at
directionstringNoSort direction for orderBy. Defaults to desc.e.g. desc
workspaceIdstring <uuid>NoExplicit workspace scope. The authenticated user must hold an active membership in this workspace. Defaults to the session workspace when omitted.e.g. a1b2c3d4-0000-4000-8000-000000000001

Request

cURL
curl -X GET https://api.wellapp.ai/v1/transactions \
  -H "Authorization: Bearer $WELL_API_TOKEN"

Responses

200 — A page of transactions.

{
  "data": [
    {
      "type": "transaction",
      "id": "f0e1d2c3-0000-4000-8000-0000000000a1",
      "attributes": {
        "transaction_id": "f0e1d2c3-0000-4000-8000-0000000000a1",
        "transaction_external_id": "txn_stripe_3PqRb2",
        "type": "credit",
        "status": "booked",
        "scheme": "sepa_credit_transfer",
        "instructed_amount": {
          "amount": 4820.5,
          "currency": "USD"
        },
        "settlement_amount": {
          "amount": 4820.5,
          "currency": "USD"
        },
        "fees": null,
        "foreign_exchange": null,
        "remittance": {
          "unstructured": "STRIPE PAYOUT FOLDSPACE AI"
        },
        "booking_date": "2026-04-27",
        "value_date": "2026-04-27",
        "executed_at": "2026-04-27T09:14:32Z",
        "category_normalized": "platform_payout",
        "category_source": "model",
        "category_confidence": 0.97,
        "created_at": "2026-04-27T09:15:00Z",
        "updated_at": "2026-04-27T09:15:00Z",
        "deleted_at": null
      },
      "relationships": {
        "debtor_payment_means": {
          "data": {
            "type": "PaymentMeans",
            "id": "00000000-0000-4000-8000-000000000001"
          }
        },
        "creditor_payment_means": {
          "data": {
            "type": "PaymentMeans",
            "id": "00000000-0000-4000-8000-000000000001"
          }
        },
        "account_balance": {
          "data": {
            "type": "AccountBalance",
            "id": "00000000-0000-4000-8000-000000000001"
          }
        },
        "sourceWorkspaceConnector": {
          "data": {
            "type": "WorkspaceConnector",
            "id": "00000000-0000-4000-8000-000000000001"
          }
        },
        "ledger_account": {
          "data": {
            "type": "LedgerAccount",
            "id": "00000000-0000-4000-8000-000000000001"
          }
        },
        "transaction_documents": {
          "data": [
            {
              "type": "TransactionDocument",
              "id": "00000000-0000-4000-8000-000000000001"
            }
          ]
        },
        "transactionWorkspaceConnectors": {
          "data": [
            {
              "type": "TransactionWorkspaceConnector",
              "id": "00000000-0000-4000-8000-000000000001"
            }
          ]
        }
      }
    }
  ],
  "meta": {
    "total": 1,
    "count": 1
  },
  "links": {
    "next": null
  }
}

400 — Bad request

{
  "code": "BAD_REQUEST",
  "status": 400,
  "title": "Bad Request",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

401 — Unauthorized

{
  "code": "UNAUTHORIZED",
  "status": 401,
  "title": "Unauthorized",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

Filtering & sorting on related objects

Filter and sort on a related (included) object by nesting into the relationship — the same relationships you pass to include.

  • To-one relations nest directly: { "issuer": { "name": { "_eq": "Acme" } } }, and sort by a dot-path: "orderBy": { "field": "issuer.name", "direction": "asc" }.
  • To-many relations must be quantified with _some, _every, or _none: { "items": { "_some": { "quantity": { "_gt": 1 } } } }. They are not directly sortable (a to-many sort needs an aggregate proxy).
  • Composite composite_* columns are virtual — filter and sort on their underlying source fields, not on the composite.

Workspace row-level security applies at every hop, so a related-object filter never widens your tenant scope. Full operator set, deep-nesting rules, and pagination notes: Filtering & sorting.

This resource's related objects (the ones you can include) and how to filter or sort on each:

RelationshipCardinalityFilter on a fieldSort by a field
workspaceto-one (Workspace){ "workspace": { "field_name": { "_eq": … } } }"field": "workspace.field_name" ✅
debtor_payment_meansto-one (PaymentMeans){ "debtor_payment_means": { "field_name": { "_eq": … } } }"field": "debtor_payment_means.field_name" ✅
creditor_payment_meansto-one (PaymentMeans){ "creditor_payment_means": { "field_name": { "_eq": … } } }"field": "creditor_payment_means.field_name" ✅
account_balanceto-one (AccountBalance){ "account_balance": { "field_name": { "_eq": … } } }"field": "account_balance.field_name" ✅
sourceWorkspaceConnectorto-one (WorkspaceConnector){ "sourceWorkspaceConnector": { "field_name": { "_eq": … } } }"field": "sourceWorkspaceConnector.field_name" ✅
ledger_accountto-one (LedgerAccount){ "ledger_account": { "field_name": { "_eq": … } } }"field": "ledger_account.field_name" ✅
transaction_documentsto-many (TransactionDocument){ "transaction_documents": { "_some": { "field_name": { "_eq": … } } } }aggregate proxy only ⚠️
transactionWorkspaceConnectorsto-many (TransactionWorkspaceConnector){ "transactionWorkspaceConnectors": { "_some": { "field_name": { "_eq": … } } } }aggregate proxy only ⚠️

Replace field_name with any field of the related object. See its object-reference page for the full field list.

Filter by a to-one relation (and sort by it):

{
  "root": "transactions",
  "whereClause": { "workspace": { "field_name": { "_ilike": "%acme%" } } },
  "orderBy": { "field": "workspace.field_name", "direction": "asc" }
}

Filter by a to-many relation (quantified — bare nesting is invalid):

{
  "root": "transactions",
  "whereClause": { "transaction_documents": { "_some": { "field_name": { "_gt": 0 } } } }
}