---
title: "List transactions"
method: GET
path: "/transactions"
tags: ["Transactions"]
---

# List transactions

`GET /transactions`

## Request

- Base URL: `https://api.toriihq.com/v1.0`
- URL: `https://api.toriihq.com/v1.0/transactions`
- Auth: API key in header `Authorization`

Returns recognized (mapped) expense transactions by default.<br/><br/>Request `mappingReason` in `fields` to see why a transaction has its matching status (e.g. `The ignored word "trip" was found`, `Search term "atlassian" is the longest found`).<br/><br/>`amount` is an object: `value`/`currency` are the original transaction amount; `convertedValue` is that amount in the organization display currency. Values are in minor currency units (e.g., cents).<br/><br/>Cursor-paginated: pass `size` for the page size and the returned `nextCursor` as `cursor` for the next page.<br/><br/>Sort with `sort=<field>:asc|desc`; sorting by `amount` uses the display-currency converted value. See `transactionSortSchema` for the sortable fields.<br/><br/>Bound a period with `filters` on `transactionDate`, using the `dayOnOrAfter` / `dayOnOrBefore` operators — they match whole days, so a time component in the value is ignored rather than cutting that day short.<br/><br/>Use `aggs` for spend totals and breakdowns instead of paging through transactions and summing them client-side. Pair it with a `transactionDate` filter to bound the period and `size=1` to keep the response compact — the numbers come back in `aggregations`.<br/><br/>Example — spend per app for 2026 year-to-date (`aggs` and `filters` are JSON and must be URL-encoded; shown decoded here for readability):<br/><br/>```GET /transactions?size=1&filters=[{"key":"transactionDate","op":"dayOnOrAfter","value":"2026-01-01"},{"key":"transactionDate","op":"dayOnOrBefore","value":"2026-08-31"}]&aggs={"field":"appName","aggregationType":"groupBy","options":{"size":100,"sort":{"order":"desc","aggFunc":"sum","field":"amount"}},"aggs":[{"field":"amount","aggregationType":"metric","options":{"metricFunction":"sum"}}]}```<br/><br/>Reading the result — in a `groupBy` bucket, `value` is the **transaction count**, not the amount. The metric you asked for is in the bucket's own `aggregations`: `[{"key":"slack","value":37,"aggregations":{"amount":106414875}}]` means 37 transactions totalling 1064148.75 in display currency. Reading `value` as money is the most common way to get this wrong.<br/><br/>A trailing `{"key":"Other"}` bucket rolls up everything past `options.size` (max 100) and carries no `aggregations` — skip it or widen the window.<br/><br/>Aggregated amounts are in the organization display currency, in minor units (cents). `appName` group keys are lower-cased (the field is indexed with a lowercase normalizer); group by `idApp` instead when you need the exact name casing.<br/><br/>
<p><ul><li>Rate limit: 100 requests per minute</li></ul></p>

## Query parameters

- `idApp` integer
- `source` string
- `q` string
- `mappingStatus` string
- `sort` string
- `size` integer
- `cursor` string
- `fields` string
- `filters` string
- `aggs` string

## Response `200`

Transactions

- Model14: Transactions
  - `transactions` Transaction[]
    - `id` integer: Unique identifier
    - `idApp` integer: Unique app identifier
    - `appName` string: Name of the matched app
    - `idAppAccount` integer: Unique app account identifier
    - `appAccountName` string: App account name
    - `idUpload` integer: Upload identifier
    - `fileName` string: Name of the source file the transaction was imported from
    - `transactionDate` string, date-time: Date of the transaction
    - `origTransactionDate` string, date-time: Original date of the transaction
    - `amount` TransactionAmount: Original amount with its currency, plus the value converted to the org display currency
      - `value` integer: Original amount (or the modified amount, if set) in minor currency units (e.g., cents)
      - `currency` string: Original currency of the transaction
      - `convertedValue` integer: The amount converted to the org display currency, in minor currency units (e.g., cents)
    - `source` string: Source the transaction was ingested from (e.g., netsuite, expensify, billcom, csv, cdw)
    - `description` string: Transaction description
    - `extraInfo` string: Additional information from the source system
    - `department` string: Department
    - `domain` string: Domain
    - `externalAccountId` string: GL account identifier in the source system
    - `externalAccountName` string: GL account name in the source system
    - `mappingStatus` 'ignored' | 'recommend_ignore' | 'recommend_map' | 'unknown' | 'mapped' | 'archived': Mapping status of the transaction
    - `mappingLogic` string: How the transaction was matched to an app
    - `mappingReason` string: Why the transaction has its matching status, as recorded by the matching rules. Empty when no rule matched.
    - `reportedBy` integer: Unique user identifier
    - `reportedByFullName` string: Full name of the user who reported the transaction
    - `idExternalTransaction` string: Identifier of the transaction in the source system
  - `aggregations` number
  - `count` integer: The number of results returned in this response
  - `total` integer: The total number of results
  - `nextCursor` string: A base64 string indicating the offset from which to start. <br>Pass the value of `nextCursor` returned from the previous call to get the next set of results

---

[API](https://skmtc.dev/toriihq/apis/torii-api-documentation.md) - [All operations](https://skmtc.dev/toriihq/apis/torii-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/toriihq/apis/torii-api-documentation/revisions/15fd1512591b?raw)