> ## Documentation Index > Fetch the complete documentation index at: https://docs.tracefinance.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a report > Aggregated view of operations over a time window, partitioned by asset. ## OpenAPI ````yaml apis/fx-payment/openapi.yml GET /v1/reports openapi: 3.1.1 info: title: Trace Finance Payments API version: 1.0.0 description: > API for deposits, withdrawals, swaps, and beneficiary management on the Trace Finance platform. servers: - url: https://api.sandbox.tracefinance.com description: Sandbox security: - bearerAuth: [] tags: - name: Operations description: >- Create deposits, withdrawals, and swaps. Query operation status and history. - name: Reports description: Generate aggregated views of operations across a time window. - name: Beneficiaries description: >- Manage external beneficiaries and their payment instructions for withdrawals. - name: Payment instructions description: Add or remove payment instructions on an existing beneficiary. paths: /v1/reports: get: tags: - Reports summary: Get a report description: > Generates an aggregated view of operations over a time window. Activity is partitioned by `asset` because amounts in different currencies cannot be summed. Only settled transactions (`CONFIRMED` status) on operations matching `filters` contribute — pending and failed are excluded. The report is regenerated on each request and is not persisted. operationId: getReport parameters: - $ref: '#/components/parameters/TraceVersion' - $ref: '#/components/parameters/PeriodStart' - $ref: '#/components/parameters/PeriodEnd' - $ref: '#/components/parameters/Filters' description: > Common filters for reports: - `account.id[eq]=a1b2c3d4-5e6f-7890-abcd-ef1234567890` — single account - `asset[eq]=USDT` — specific currency - `tags.key[eq]=psp` — operations carrying a tag with this key - `tags.value[eq]=Amazon` — operations carrying a tag with this value See the [Filtering](/guides/principles/filtering) guide for the LHS Brackets syntax and the full operator catalog. responses: '200': description: Aggregated report for the requested window. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ReportResponse' examples: multiAssetActivity: $ref: '#/components/examples/ReportMultiAssetActivity' withdrawalsOnly: $ref: '#/components/examples/ReportWithdrawalsOnly' emptyPeriod: $ref: '#/components/examples/ReportEmptyPeriod' '401': $ref: '#/components/responses/UnauthorizedError' '422': description: Invalid query parameter or filter expression. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingPeriodStart: $ref: '#/components/examples/ReportMissingPeriodStart' periodEndNotAfterStart: $ref: '#/components/examples/ReportPeriodEndNotAfterStart' components: parameters: TraceVersion: name: X-Trace-Version in: header required: false description: API version. Omit to use the default version. schema: type: string example: '1' PeriodStart: name: periodStart in: query required: true description: > Inclusive start of the reporting window. UTC timestamp in ISO 8601 format — the `Z` suffix is the timezone marker and is required (e.g., `2026-04-01T00:00:00Z`). See the [Date and time](/guides/principles/datetime) guide for the full format. schema: type: string format: date-time example: '2026-04-01T00:00:00Z' PeriodEnd: name: periodEnd in: query required: true description: > Exclusive end of the reporting window. UTC timestamp in ISO 8601 format — the `Z` suffix is the timezone marker and is required (e.g., `2026-05-01T00:00:00Z`). Must be strictly greater than `periodStart`. See the [Date and time](/guides/principles/datetime) guide for the full format. schema: type: string format: date-time example: '2026-05-01T00:00:00Z' Filters: name: filters in: query required: false description: > Filter expression using LHS Brackets syntax (`field[operator]=value`). Combine multiple conditions with `and(...)`, `or(...)`, or `;` (implicit AND). See the [Filtering](/guides/principles/filtering) guide for the full operator catalog. schema: type: string example: intent.type[eq]=WITHDRAWAL;currentState.status[eq]=COMPLETED headers: RequestId: description: >- Unique request identifier emitted on every response. Reference it when contacting Trace Finance support so we can trace the request end-to-end. See [Errors](/guides/principles/errors). schema: type: string format: uuid schemas: ReportResponse: type: object description: >- Aggregated view of operations over a time window. Generated on each request — not persisted. properties: period: $ref: '#/components/schemas/ReportPeriod' totals: type: array description: >- One entry per asset that had at least one settled transaction matching the filter in the period. Empty when nothing matched. items: $ref: '#/components/schemas/ReportTotal' required: - period - totals ErrorResponse: type: object properties: code: type: string description: Machine-readable error code. message: type: string description: Human-readable description. details: type: object additionalProperties: true required: - code - message ReportPeriod: type: object description: >- The reporting window. Boundary semantics are half-open — `start` inclusive, `end` exclusive. properties: start: type: string format: date-time description: Inclusive start of the reporting window. example: '2026-04-01T00:00:00Z' end: type: string format: date-time description: Exclusive end of the reporting window. example: '2026-05-01T00:00:00Z' required: - start - end ReportTotal: type: object description: >- Inflows and outflows for one asset over the reporting window. A row is present only when at least one settled transaction in that asset matched the filter. properties: asset: $ref: '#/components/schemas/Asset' inflows: $ref: '#/components/schemas/ReportAggregate' outflows: $ref: '#/components/schemas/ReportAggregate' required: - asset Asset: type: string enum: - BRL - USDT - USDC description: > ISO 4217 currency code or stablecoin ticker. The maximum decimal scale of an `AmountValue` paired with this asset depends on the asset: | Asset | Decimals | |---|---| | BRL | 2 | | USDT | 6 | | USDC | 6 | example: BRL ReportAggregate: type: object description: >- Sum and count of monetary movements on a single side of the ledger within an asset partition. properties: sum: $ref: '#/components/schemas/AmountResponse' count: type: integer minimum: 0 description: Number of contributing transactions. example: 3 required: - sum - count AmountResponse: type: object description: > Monetary amount expressed as a decimal string in the asset's canonical scale. Use a decimal-precision library (`BigDecimal`, `Decimal`) for arithmetic — never JavaScript `Number`. Request bodies use the scalar `AmountValue` instead. properties: value: type: string pattern: ^-?\d+(\.\d+)?$ description: Decimal amount in the asset's canonical scale. example: '500.00' asset: $ref: '#/components/schemas/Asset' decimals: type: integer description: Number of decimal places for the asset. example: 2 required: - value - asset - decimals examples: ReportMultiAssetActivity: summary: Mixed deposits and withdrawals across BRL and USDT value: period: start: '2026-04-01T00:00:00Z' end: '2026-05-01T00:00:00Z' totals: - asset: BRL inflows: sum: value: '5000.00' asset: BRL decimals: 2 count: 2 outflows: sum: value: '10000.00' asset: BRL decimals: 2 count: 2 - asset: USDT outflows: sum: value: '2000.000000' asset: USDT decimals: 6 count: 2 ReportWithdrawalsOnly: summary: Filtered to withdrawals only — no inflows value: period: start: '2026-04-01T00:00:00Z' end: '2026-05-01T00:00:00Z' totals: - asset: BRL outflows: sum: value: '10000.00' asset: BRL decimals: 2 count: 2 - asset: USDT outflows: sum: value: '2000.000000' asset: USDT decimals: 6 count: 2 ReportEmptyPeriod: summary: No settled transactions matched the filter in the period value: period: start: '2026-04-01T00:00:00Z' end: '2026-05-01T00:00:00Z' totals: [] ReportMissingPeriodStart: summary: periodStart is missing from the query string value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: REQUIRED message: Parameter 'query:periodStart' not found in request field: query:periodStart params: {} ReportPeriodEndNotAfterStart: summary: periodEnd must be strictly greater than periodStart value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: INVALID_RANGE message: '''periodEnd'' must be greater than ''periodStart''' field: query:periodEnd params: periodStart: '2026-05-01T00:00:00Z' periodEnd: '2026-04-01T00:00:00Z' InvalidToken: summary: Bearer token is invalid or malformed value: code: INVALID_ACCESS_TOKEN message: Invalid access token details: {} ExpiredToken: summary: Bearer token has expired value: code: EXPIRED_ACCESS_TOKEN message: Expired access token details: {} responses: UnauthorizedError: description: Missing or invalid authentication token. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidToken: $ref: '#/components/examples/InvalidToken' expiredToken: $ref: '#/components/examples/ExpiredToken' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer token. Include as `Authorization: Bearer `. See the [Authentication](/guides/authentication) guide for how to obtain one. ````