> ## Documentation Index > Fetch the complete documentation index at: https://docs.kirafin.ai/llms.txt > Use this file to discover all available pages before exploring further. # List payouts > List the payouts under your account, newest first. The rows arrive in `payouts`. Alongside them, `total` reports how many match your filters and `total_pages` how many pages that is. An unknown query parameter is rejected with a `400` rather than ignored, so a typo tells you. ## OpenAPI ````yaml /openapi/kira-api.2026-04-14.json get /v1/payouts openapi: 3.1.0 info: title: Kira API version: '2026-04-14' description: >- REST API for users, KYC/KYB verification, virtual accounts, payouts, recipients, and webhooks. Every request requires an `x-api-key` header and a bearer access token (see Authentication). Pin your account to version `2026-04-14` before integrating. contact: name: Kira API Support email: support@kirafin.ai servers: - url: https://api.balampay.com description: Production - url: https://api.balampay.com/sandbox description: Sandbox security: - bearerAuth: [] apiKeyAuth: [] tags: - name: Authentication - name: Versioning - name: Users - name: Virtual Accounts - name: Recipients - name: Quotations - name: Payouts - name: Reference paths: /v1/payouts: get: tags: - Payouts summary: List payouts description: >- List the payouts under your account, newest first. The rows arrive in `payouts`. Alongside them, `total` reports how many match your filters and `total_pages` how many pages that is. An unknown query parameter is rejected with a `400` rather than ignored, so a typo tells you. operationId: get_v1-payouts parameters: - in: header name: X-Api-Version required: false description: >- Version applied to this request. It wins over your account's pinned version — see [Versioning](/using-the-api/versioning). schema: type: string example: '2026-04-14' - in: query name: page required: false description: >- Which page to return, counting from `1`. This list pages by number, not by offset. schema: type: integer minimum: 1 default: 1 - in: query name: limit required: false description: >- How many payouts to return. Between `1` and `100`, and `10` when you omit it. schema: type: integer minimum: 1 maximum: 100 default: 10 - in: query name: status required: false description: >- Filter by payout status. Available options: `CREATED`, `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `CANCELLED`, `IN_REVIEW`, `KYT_PENDING`. See [Payout values](/reference/payouts/values#payout-status). schema: type: string - in: query name: origin required: false description: >- Filter by what started the payout. Available options: `deposit`, `payout`, `api`. See [Payout values](/reference/payouts/values#payout-origin). schema: type: string - in: query name: user_id required: false description: Return only the payouts belonging to this user. schema: type: string format: uuid - in: query name: recipient_id required: false description: Return only the payouts that went to this recipient. schema: type: string format: uuid - in: query name: virtual_account_id required: false description: Return only the payouts that left this account. schema: type: string format: uuid - in: query name: from_date required: false description: >- Return only payouts created from this moment on. Send a full ISO 8601 timestamp or just a date as `YYYY-MM-DD`. schema: type: string - in: query name: to_date required: false description: >- Return only payouts created up to this moment. Send a full ISO 8601 timestamp or just a date as `YYYY-MM-DD`. schema: type: string - in: query name: search required: false description: Free-text search over the payout. Up to 255 characters. schema: type: string maxLength: 255 - in: query name: sort_by required: false description: >- Which field to sort on. Available options: `created_at`, `from_amount`, `status`. `created_at` when you omit it. schema: type: string - in: query name: sort_order required: false description: |- Which way to sort. Available options: `asc`, `desc`. `desc` when you omit it. schema: type: string - in: query name: metadata required: false description: >- Return only the payouts carrying the metadata you name, in the `?metadata[key]=value` form. Pass more than one key to require all of them. Each key is 1 to 40 characters and cannot contain `[` or `]`. schema: type: object style: deepObject explode: true responses: '200': description: Success. content: application/json: schema: type: object properties: payouts: type: array items: $ref: '#/components/schemas/PayoutListItem' total: type: integer description: Total number of payouts matching the filters. page: type: integer description: The page returned. limit: type: integer description: The limit applied to this page. total_pages: type: integer description: How many pages the filters produce at this limit. example: payouts: - payout_id: 99999999-aaaa-bbbb-cccc-dddddddddddd short_id: '042' user_id: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee virtual_account_id: 11111111-2222-3333-4444-555555555555 created_at: '2026-09-01T12:00:00.000Z' status: COMPLETED origin: payout from_amount: '1000.00' from_currency: USD to_amount: '986.50' to_currency: USD payment_method: wire sender_name: Northwind Trading LLC recipient_name: Acme Supplies LLC reference: INV-2026-0042 memo: September invoice metadata: {} total: 42 page: 1 limit: 10 total_pages: 5 '400': description: >- A query parameter is out of range, is not one of the values it accepts, or is not a parameter this call takes. An unknown one is named in `details.unknown_params`. content: application/json: schema: type: object properties: statusCode: type: integer description: Repeats the HTTP status. error: type: string description: Always `Bad Request`. message: type: string description: What went wrong, in one sentence. timestamp: type: string description: When the call was rejected, as an ISO 8601 timestamp. path: type: string description: The path you called. code: type: string description: A short machine-readable reason. details: type: object additionalProperties: true description: The values involved. examples: bad-value: summary: A value is out of range value: statusCode: 400 error: Bad Request message: Invalid query parameters timestamp: '2026-09-01T12:00:00.000Z' path: /v1/payouts code: VALIDATION_ERROR details: limit: - Number must be less than or equal to 100 unknown-param: summary: A parameter this call does not take value: statusCode: 400 error: Bad Request message: Invalid query parameters timestamp: '2026-09-01T12:00:00.000Z' path: /v1/payouts code: VALIDATION_ERROR details: unknown_params: - stauts '401': description: >- Your credentials could not be read. The message talks about routing, but the cause is one of these: - The `Authorization` header is missing. - The token is not a token, or was not issued for your account. - The `x-api-key` header is missing or wrong. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: invalid_request message: >- The request could not be matched to a valid route, or was malformed. Verify the path and HTTP method against the API reference. This is a routing or request error, not a credentials or signature problem. security: - bearerAuth: [] apiKeyAuth: [] servers: - url: https://api.balampay.com/sandbox description: Sandbox - url: https://api.balampay.com description: Production components: schemas: PayoutListItem: type: object description: One payout, as the list returns it. properties: payout_id: type: string format: uuid description: Payout UUID. This is the identifier to store. short_id: type: string description: >- A three-digit label for display. It is worked out from the row's position, so it changes as payouts are created — never store it or use it to match a payout. user_id: type: string format: uuid description: The user the payout belongs to. virtual_account_id: type: - string - 'null' description: >- The account the money left from. `null` on a payout made without one, so branch on it rather than expecting every row to have it. created_at: type: string description: When the payout was created, as an ISO 8601 timestamp. status: type: string description: >- Where the payout has got to. See [Payout values](/reference/payouts/values#payout-status). origin: type: string description: >- What started it. Available options: `deposit`, `payout`, `api`. See [Payout values](/reference/payouts/values#payout-origin). from_amount: type: string description: What left the account, as a decimal string. from_currency: type: string description: Currency of `from_amount`. to_amount: type: string description: What the recipient gets, as a decimal string. to_currency: type: - string - 'null' description: Currency of `to_amount`. `null` until it is known. payment_method: type: - string - 'null' description: >- Which rail it went out on, in lower case. Available options: `ach`, `wire`, `wallet`. `null` when the recipient can no longer be read. See [Payout values](/reference/payouts/values#payout-payment_method). sender_name: type: - string - 'null' description: Name of the user who sent it. recipient_name: type: - string - 'null' description: Name of who received it. reference: type: - string - 'null' description: The reference you set when you made the payout. memo: type: - string - 'null' description: The memo you set when you made the payout. metadata: type: object additionalProperties: true description: Key/value pairs you attached. `{}` when you attached none. ErrorResponse: type: object properties: message: type: string code: type: string statusCode: type: number error: type: string timestamp: type: string path: type: string details: {} required: - message securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- The `data.access_token` value from [Get access token](/api-reference/authentication/get-access-token). apiKeyAuth: type: apiKey in: header name: x-api-key description: API key issued by Kira. ````