> ## Documentation Index > Fetch the complete documentation index at: https://docs.lightspark.com/llms.txt > Use this file to discover all available pages before exploring further. # List agents > Retrieve a paginated list of agents for the authenticated platform. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/grid/openapi.documented.yml get /agents openapi: 3.1.0 info: title: Grid API description: > API for managing global payments on the open Money Grid. Built by Lightspark. See the full documentation at https://docs.lightspark.com/. version: '2025-10-13' contact: name: Lightspark Support email: support@lightspark.com license: name: Proprietary url: https://lightspark.com/terms servers: - url: https://api.lightspark.com/grid/2025-10-13 description: Production server security: - BasicAuth: [] - AgentAuth: [] tags: - name: Platform Configuration description: >- Platform configuration endpoints for managing global settings. You can also configure these settings in the Grid dashboard. - name: Customers description: >- Customer management endpoints for creating and updating customer information - name: KYC/KYB Verifications description: >- Endpoints for Know Your Customer (KYC) and Know Your Business (KYB) verification, including managing beneficial owners and triggering verification for customers. - name: Documents description: >- Endpoints for uploading and managing verification documents for customers and beneficial owners. Supports KYC and KYB document requirements. - name: Internal Accounts description: >- Internal account management endpoints for creating and managing internal accounts - name: External Accounts description: >- External account management endpoints for creating and managing external bank accounts - name: Same-Currency Transfers description: >- Endpoints for transferring funds between internal and external accounts with the same currency - name: Cross-Currency Transfers description: Endpoints for creating and confirming quotes for cross-currency transfers - name: Transactions description: Endpoints for retrieving transaction information - name: Webhooks description: Webhook endpoints and configuration for receiving notifications - name: Invitations description: Endpoints for creating, claiming and managing UMA invitations - name: Sandbox description: Endpoints to trigger test cases in sandbox - name: API Tokens description: Endpoints to programmatically manage API tokens - name: Exchange Rates description: >- Endpoints for retrieving cached foreign exchange rates. Rates are cached for approximately 5 minutes and include platform-specific fees. - name: Discoveries description: >- Endpoints for discovering available payment rails, banks, and providers for a given country and currency corridor. - name: Embedded Wallet Auth description: >- Endpoints for registering and verifying end-user authentication credentials (email OTP, OAuth, passkey) used to sign Embedded Wallet actions. - name: Agent Management description: >- Endpoints for creating and managing agents (experimental), called by the partner's backend using platform credentials. Covers the full agent lifecycle: creation, policy configuration, pausing, deletion, the device code installation flow, and approving or rejecting transactions initiated by agents. - name: Agent Operations description: >- Endpoints called by the agent itself using its own credentials (obtained via device code redemption). Scoped to the agent's associated customer — all requests automatically operate on behalf of that customer and are subject to the agent's policy. When an action requires approval, the resulting transaction enters a pending state and must be approved by the platform via `POST /transactions/{transactionId}/approve`. - name: Cards description: >- Card management endpoints. Issue debit cards against an internal account, freeze / unfreeze, close, manage card funding sources, and list card transactions. paths: /agents: get: tags: - Agent Management summary: List agents description: Retrieve a paginated list of agents for the authenticated platform. operationId: listAgents parameters: - name: customerId in: query description: Filter by customer ID required: false schema: type: string - name: isPaused in: query description: Filter by paused status required: false schema: type: boolean - name: isConnected in: query description: >- Filter by connection status (whether the device code has been redeemed) required: false schema: type: boolean - name: createdAfter in: query description: Filter agents created after this timestamp (inclusive) required: false schema: type: string format: date-time - name: createdBefore in: query description: Filter agents created before this timestamp (inclusive) required: false schema: type: string format: date-time - name: updatedAfter in: query description: Filter agents updated after this timestamp (inclusive) required: false schema: type: string format: date-time - name: updatedBefore in: query description: Filter agents updated before this timestamp (inclusive) required: false schema: type: string format: date-time - name: limit in: query description: Maximum number of results to return (default 20, max 100) required: false schema: type: integer minimum: 1 maximum: 100 default: 20 - name: cursor in: query description: Cursor for pagination (returned from previous request) required: false schema: type: string responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/AgentListResponse' '400': description: Bad request - Invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error401' '500': description: Internal service error content: application/json: schema: $ref: '#/components/schemas/Error500' security: - BasicAuth: [] x-codeSamples: - lang: JavaScript source: |- import LightsparkGrid from '@lightsparkdev/grid'; const client = new LightsparkGrid({ username: process.env['GRID_CLIENT_ID'], // This is the default and can be omitted password: process.env['GRID_CLIENT_SECRET'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const agent of client.agents.list()) { console.log(agent.id); } - lang: Python source: |- import os from grid import LightsparkGrid client = LightsparkGrid( username=os.environ.get("GRID_CLIENT_ID"), # This is the default and can be omitted password=os.environ.get("GRID_CLIENT_SECRET"), # This is the default and can be omitted ) page = client.agents.list() page = page.data[0] print(page.id) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/stainless-sdks/grid-go\"\n\t\"github.com/stainless-sdks/grid-go/option\"\n)\n\nfunc main() {\n\tclient := grid.NewClient(\n\t\toption.WithUsername(\"My Username\"),\n\t\toption.WithPassword(\"My Password\"),\n\t)\n\tpage, err := client.Agents.List(context.TODO(), grid.AgentListParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", page)\n}\n" - lang: Kotlin source: |- package com.lightspark.grid.example import com.lightspark.grid.client.LightsparkGridClient import com.lightspark.grid.client.okhttp.LightsparkGridOkHttpClient import com.lightspark.grid.models.agents.AgentListPage import com.lightspark.grid.models.agents.AgentListParams fun main() { val client: LightsparkGridClient = LightsparkGridOkHttpClient.fromEnv() val page: AgentListPage = client.agents().list() } - lang: Ruby source: >- require "grid" lightspark_grid = Grid::Client.new(username: "My Username", password: "My Password") page = lightspark_grid.agents.list puts(page) - lang: PHP source: |- agents->list( createdAfter: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdBefore: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), cursor: 'cursor', customerID: 'customerId', isConnected: true, isPaused: true, limit: 1, updatedAfter: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), updatedBefore: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), ); var_dump($page); } catch (APIException $e) { echo $e->getMessage(); } - lang: C# source: |- using System; using Grid; using Grid.Models.Agents; LightsparkGridClient client = new(); AgentListParams parameters = new(); var page = await client.Agents.List(parameters); await foreach (var item in page.Paginate()) { Console.WriteLine(item); } - lang: CLI source: |- grid agents list \ --username 'My Username' \ --password 'My Password' components: schemas: AgentListResponse: type: object required: - data - hasMore properties: data: type: array description: List of agents matching the filter criteria. items: $ref: '#/components/schemas/Agent' hasMore: type: boolean description: Indicates if more results are available beyond this page. nextCursor: type: string description: >- Cursor to retrieve the next page of results (only present if hasMore is true). totalCount: type: integer description: Total number of agents matching the criteria (excluding pagination). Error400: type: object required: - message - status - code properties: status: type: integer enum: - 400 description: HTTP status code code: type: string description: > | Error Code | Description | |------------|-------------| | INVALID_INPUT | Invalid input provided | | MISSING_MANDATORY_USER_INFO | Required customer information is missing | | INVITATION_ALREADY_CLAIMED | Invitation has already been claimed | | INVITATIONS_NOT_CONFIGURED | Invitations are not configured | | INVALID_UMA_ADDRESS | UMA address format is invalid | | INVITATION_CANCELLED | Invitation has been cancelled | | QUOTE_REQUEST_FAILED | An issue occurred during the quote process; this is retryable | | INVALID_PAYREQ_RESPONSE | Counterparty Payreq response was invalid | | INVALID_RECEIVER | Receiver is invalid | | PARSE_PAYREQ_RESPONSE_ERROR | Error parsing receiver PayReq response | | CERT_CHAIN_INVALID | Counterparty certificate chain is invalid | | CERT_CHAIN_EXPIRED | Counterparty certificate chain has expired | | INVALID_PUBKEY_FORMAT | Counterparty Public key format is invalid | | MISSING_REQUIRED_UMA_PARAMETERS | Counterparty required UMA parameters are missing | | SENDER_NOT_ACCEPTED | Sender is not accepted | | AMOUNT_OUT_OF_RANGE | Amount is out of range | | INVALID_CURRENCY | Currency is invalid | | INVALID_TIMESTAMP | Timestamp is invalid | | INVALID_NONCE | Nonce is invalid | | INVALID_REQUEST_FORMAT | Request format is invalid | | INVALID_BANK_ACCOUNT | Bank account is invalid | | SELF_PAYMENT | Self payment not allowed | | LOOKUP_REQUEST_FAILED | Lookup request failed | | PARSE_LNURLP_RESPONSE_ERROR | Error parsing LNURLP response | | INVALID_AMOUNT | Amount is invalid | | WEBHOOK_ENDPOINT_NOT_SET | Webhook endpoint is not set | | WEBHOOK_DELIVERY_ERROR | Webhook delivery error | | LOW_QUALITY | Document quality too low to process | | DATA_MISMATCH | Document details don't match provided information | | EXPIRED | Document has expired | | SUSPECTED_FRAUD | Document suspected of being forged or edited | | UNSUITABLE_DOCUMENT | Document type is not accepted or not supported | | INCOMPLETE | Document is missing pages or sides | | EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS | An EMAIL_OTP credential is already registered on the target internal account; only one email OTP credential is supported per internal account at this time | | PASSKEY_CREDENTIAL_ALREADY_EXISTS | A PASSKEY credential with the same WebAuthn credentialId is already registered on the target internal account | enum: - INVALID_INPUT - MISSING_MANDATORY_USER_INFO - INVITATION_ALREADY_CLAIMED - INVITATIONS_NOT_CONFIGURED - INVALID_UMA_ADDRESS - INVITATION_CANCELLED - QUOTE_REQUEST_FAILED - INVALID_PAYREQ_RESPONSE - INVALID_RECEIVER - PARSE_PAYREQ_RESPONSE_ERROR - CERT_CHAIN_INVALID - CERT_CHAIN_EXPIRED - INVALID_PUBKEY_FORMAT - MISSING_REQUIRED_UMA_PARAMETERS - SENDER_NOT_ACCEPTED - AMOUNT_OUT_OF_RANGE - INVALID_CURRENCY - INVALID_TIMESTAMP - INVALID_NONCE - INVALID_REQUEST_FORMAT - INVALID_BANK_ACCOUNT - SELF_PAYMENT - LOOKUP_REQUEST_FAILED - PARSE_LNURLP_RESPONSE_ERROR - INVALID_AMOUNT - WEBHOOK_ENDPOINT_NOT_SET - WEBHOOK_DELIVERY_ERROR - LOW_QUALITY - DATA_MISMATCH - EXPIRED - SUSPECTED_FRAUD - UNSUITABLE_DOCUMENT - INCOMPLETE - EMAIL_OTP_CREDENTIAL_ALREADY_EXISTS - PASSKEY_CREDENTIAL_ALREADY_EXISTS message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Error401: type: object required: - message - status - code properties: status: type: integer enum: - 401 description: HTTP status code code: type: string description: > | Error Code | Description | |------------|-------------| | UNAUTHORIZED | Issue with API credentials | | INVALID_SIGNATURE | Signature header is invalid | | WALLET_SIGNATURE_MISSING | The `Grid-Wallet-Signature` header is required for this Embedded Wallet action but was not supplied | | WALLET_SIGNATURE_MALFORMED | The `Grid-Wallet-Signature` header could not be parsed (bad encoding, structure, or fields) | | WALLET_SIGNATURE_BODY_MISMATCH | The `Grid-Wallet-Signature` was computed over a different request body than the one received | | WALLET_SIGNATURE_INVALID | The `Grid-Wallet-Signature` failed cryptographic verification against the registered credential | | REQUEST_ID_MISSING | The `Request-Id` header is required on the signed retry but was not supplied (paired with `Grid-Wallet-Signature`) | enum: - UNAUTHORIZED - INVALID_SIGNATURE - WALLET_SIGNATURE_MISSING - WALLET_SIGNATURE_MALFORMED - WALLET_SIGNATURE_BODY_MISMATCH - WALLET_SIGNATURE_INVALID - REQUEST_ID_MISSING message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Error500: type: object required: - message - status - code properties: status: type: integer enum: - 500 description: HTTP status code code: type: string description: | | Error Code | Description | |------------|-------------| | GRID_SWITCH_ERROR | Grid switch error | | INTERNAL_ERROR | Internal server or UMA error | enum: - GRID_SWITCH_ERROR - INTERNAL_ERROR message: type: string description: Error message details: type: object description: Additional error details additionalProperties: true Agent: type: object description: >- A programmatic agent with scoped permissions and a spending policy, used to automate payment workflows. required: - id - name - customerId - isPaused - isConnected - policy - usage - createdAt - updatedAt properties: id: type: string description: System-generated unique identifier for the agent. example: Agent:019542f5-b3e7-1d02-0000-000000000001 name: type: string description: Human-readable name for the agent. example: Payroll Automation Agent customerId: type: string description: The ID of the customer this agent operates on behalf of. example: Customer:019542f5-b3e7-1d02-0000-000000000001 isPaused: type: boolean description: >- Whether the agent is currently paused. Paused agents cannot initiate any actions. example: false isConnected: type: boolean description: >- Whether the agent has been installed and connected (i.e., its device code has been redeemed). example: true policy: $ref: '#/components/schemas/AgentPolicy' usage: $ref: '#/components/schemas/AgentUsage' createdAt: type: string format: date-time description: Creation timestamp. example: '2025-07-21T17:32:28Z' updatedAt: type: string format: date-time description: Last update timestamp. example: '2025-07-21T17:32:28Z' AgentPolicy: type: object description: >- Policy governing what an agent can do, how it executes actions, and its spending boundaries. required: - permissions - defaultExecutionMode - spendingLimits properties: permissions: type: array description: List of permissions granted to the agent. items: $ref: '#/components/schemas/AgentPermission' defaultExecutionMode: $ref: '#/components/schemas/AgentExecutionMode' spendingLimits: $ref: '#/components/schemas/AgentSpendingLimits' accountRestrictions: $ref: '#/components/schemas/AgentAccountRestrictions' approvalThresholds: $ref: '#/components/schemas/AgentApprovalThresholds' AgentUsage: type: object description: >- Real-time counters tracking the agent's spending and transaction activity against its policy limits. required: - dailyTransactionCount - dailySpend - monthlySpend properties: dailyTransactionCount: type: integer description: Number of transactions initiated by the agent today. example: 3 dailySpend: type: integer description: >- Total amount spent by the agent today, in the smallest unit of the policy's `spendingLimits.currency`. example: 150000 dailyResetDate: type: string format: date description: The date when daily usage counters will reset. example: '2025-07-22' monthlySpend: type: integer description: >- Total amount spent by the agent this month, in the smallest unit of the policy's `spendingLimits.currency`. example: 750000 monthlyResetMonth: type: string description: The year-month (YYYY-MM) when monthly usage counters will reset. example: 2025-08 AgentPermission: type: string enum: - VIEW_TRANSACTIONS - CREATE_TRANSFERS - CREATE_QUOTES - EXECUTE_QUOTES - MANAGE_EXTERNAL_ACCOUNTS description: >- Permission granted to an agent that determines what actions it can perform. VIEW_TRANSACTIONS: Can list and retrieve transactions and account balances. CREATE_TRANSFERS: Can initiate same-currency transfers. CREATE_QUOTES: Can create cross-currency quotes. EXECUTE_QUOTES: Can execute cross-currency quotes. MANAGE_EXTERNAL_ACCOUNTS: Can create and manage external accounts. AgentExecutionMode: type: string enum: - AUTO - APPROVAL_REQUIRED description: >- Execution mode controlling whether agent actions require human approval. AUTO: The agent can execute actions autonomously without explicit approval. APPROVAL_REQUIRED: All agent actions require explicit human approval before execution. AgentSpendingLimits: type: object description: >- Spending limits that cap the agent's transaction amounts and frequency. All amount fields are integers in the smallest unit of the specified currency. When a transaction is denominated in a different currency, Grid converts using the exchange rate at evaluation time. required: - currency - perTransactionLimit properties: currency: type: string description: ISO 4217 currency code that all amount limits are denominated in. example: USD perTransactionLimit: type: integer description: Maximum amount the agent can transfer in a single transaction. example: 50000 dailyLimit: type: - integer - 'null' description: >- Maximum total amount the agent can transfer per day. Null means no daily limit. example: 500000 dailyTransactionLimit: type: integer description: Maximum number of transactions the agent can initiate per day. example: 10 monthlyLimit: type: - integer - 'null' description: >- Maximum total amount the agent can transfer per month. Null means no monthly limit. example: 5000000 AgentAccountRestrictions: type: object description: >- Optional restrictions that limit the agent to specific accounts or override policy per account. properties: allowedAccountIds: type: - array - 'null' description: >- If set, restricts the agent to operate only on the specified internal account IDs. Null means the agent can access all accounts. items: type: string example: Account:019542f5-b3e7-1d02-0000-000000000001 accountRules: type: array description: >- Per-account rules that override the agent's default policy for specific accounts. items: $ref: '#/components/schemas/AgentAccountRule' AgentApprovalThresholds: type: object description: >- Thresholds that force approval for high-value transactions, overriding the default execution mode. When a transaction is denominated in a different currency than the threshold, Grid converts using the exchange rate at evaluation time. properties: currency: type: string description: >- ISO 4217 currency code that the amount threshold is denominated in. Required when amount is set. example: USD amount: type: - integer - 'null' description: >- If set, any transaction above this amount (in the smallest unit of the specified currency) will require explicit approval even when the agent's defaultExecutionMode is AUTO. Null means no threshold override. example: 100000 AgentAccountRule: type: object description: >- Per-account policy override that takes precedence over the agent's default policy for a specific account. required: - accountId properties: accountId: type: string description: The internal account ID this rule applies to. example: Account:019542f5-b3e7-1d02-0000-000000000001 executionMode: $ref: '#/components/schemas/AgentExecutionMode' perTransactionLimit: type: - integer - 'null' description: >- Per-transaction limit override, in the smallest unit of the relevant currency. Null inherits from the agent's spending limits. example: 10000 securitySchemes: BasicAuth: type: http scheme: basic description: >- API token authentication using format `:` AgentAuth: type: http scheme: bearer description: >- Bearer token authentication for agent-scoped endpoints. The token is the `accessToken` returned when redeeming a device code via `POST /agents/device-codes/{code}/redeem`. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy. ````