> ## 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 capability grants > List what up to 100 of your sub-clients hold, as grant events. A sub-client holds a capability when its newest event for it is `granted`. The whole list comes back in one answer, with no paging. ## OpenAPI ````yaml /openapi/kira-api.2026-04-14.json get /v1/capability-grants 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 except the token call needs a bearer access token (see Authentication). Pin your account to the recommended version before integrating (see [Versioning](/using-the-api/versioning)). 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: [] tags: - name: Authentication - name: Versioning - name: Users - name: Virtual Accounts - name: Recipients - name: Quotations - name: Payouts - name: Ultimate Payors - name: Capabilities - name: Reference - name: RFIs paths: /v1/capability-grants: get: tags: - Capabilities summary: List capability grants description: >- List what up to 100 of your sub-clients hold, as grant events. A sub-client holds a capability when its newest event for it is `granted`. The whole list comes back in one answer, with no paging. operationId: get_v1-capability-grants 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: user_ids required: true description: |- Up to 100 sub-clients, comma-separated. A repeated id counts once. A sub-client that is not yours returns nothing, not an error. schema: type: string example: >- aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee,bbbbbbbb-cccc-dddd-eeee-ffffffffffff - in: query name: capability required: false description: >- Return only the events for this capability `code` — see [Values](/reference/capabilities/values#code). schema: type: string example: pobo - in: query name: latest required: false description: >- `true` keeps only each sub-client's newest event per capability, which is the one that says whether it holds it now. schema: type: string enum: - 'true' - 'false' default: 'false' responses: '200': description: The grant events. content: application/json: schema: $ref: '#/components/schemas/CapabilityGrantListResponse' example: grants: - id: 7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f user_id: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee capability: pobo kind: feature status: granted request_id: 5d2e8f14-7a3b-4c6d-9e1f-2a3b4c5d6e7f decided_at: '2026-10-20T09:12:44.103Z' source: recorded - id: null user_id: bbbbbbbb-cccc-dddd-eeee-ffffffffffff capability: jp_morgan kind: bank status: granted request_id: null decided_at: null source: projected total: 2 '400': description: >- A query parameter is missing or invalid. `errors` holds one entry per problem. content: application/json: schema: $ref: '#/components/schemas/CapabilityRequestQueryValidationError' example: code: validation_error message: Invalid query parameters errors: - field: user_ids message: Required '401': description: >- No valid bearer token came with the request. Get one from [Get access token](/api-reference/authentication/get-access-token) and send it as `Authorization: Bearer `. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: invalid_request message: >- The request was not authenticated. Request a token at POST /auth with your Client ID and your API key, then send it as Authorization: Bearer . '500': description: >- Something failed on our side. Retry, and if it keeps happening contact your Kira contact with the time of the call. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: error message: Internal server error security: - bearerAuth: [] apiKeyAuth: [] servers: - url: https://api.balampay.com/sandbox description: Sandbox - url: https://api.balampay.com description: Production x-codeSamples: - lang: curl label: cURL source: |- curl --request GET \ --url 'https://api.balampay.com/sandbox/v1/capability-grants?user_ids=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee,bbbbbbbb-cccc-dddd-eeee-ffffffffffff&latest=true' \ --header 'Authorization: Bearer ' \ --header 'x-api-key: ' components: schemas: CapabilityGrantListResponse: type: object properties: grants: type: array description: The `recorded` events newest first, then the `projected` ones. items: $ref: '#/components/schemas/CapabilityGrant' total: type: integer description: How many events are in `grants`. CapabilityRequestQueryValidationError: type: object properties: code: type: string description: Always `validation_error`. message: type: string description: Always `Invalid query parameters`. errors: type: array description: One entry per problem. items: type: object properties: field: type: string description: The parameter that was rejected. message: type: string description: What is wrong with it. 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 CapabilityGrant: type: object description: 'One grant event: a sub-client was granted a capability, or lost it.' properties: id: type: - string - 'null' description: The event's identifier. `null` when `source` is `projected`. user_id: type: string format: uuid description: The sub-client the event is about. capability: type: string description: >- The capability's `code`. See [Capability values](/reference/capabilities/values#code). kind: type: string description: >- Available options: `feature`, `bank`. See [Capability values](/reference/capabilities/values#kind). status: type: string description: >- Available options: `granted`, `revoked`. See [Capability request values](/reference/capabilities/values#grant-status). request_id: type: - string - 'null' description: >- The capability request whose approval granted it. `null` on a `bank`. decided_at: type: - string - 'null' description: >- When the event happened, as an ISO 8601 timestamp. `null` when `source` is `projected`. source: type: string description: >- Available options: `recorded`, `projected`. See [Capability values](/reference/capabilities/values#grant-source). securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- The `data.access_token` value from [Get access token](/api-reference/authentication/get-access-token). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.