---
title: "List agents"
method: GET
path: "/agents"
tags: ["Agent Management"]
---

# List agents

`GET /agents`

Retrieve a paginated list of agents for the authenticated platform.

## Query parameters

- `customerId` string
- `isPaused` boolean
- `isConnected` boolean
- `createdAfter` string, date-time
- `createdBefore` string, date-time
- `updatedAfter` string, date-time
- `updatedBefore` string, date-time
- `limit` integer
- `cursor` string

## Response `200`

Successful operation

- AgentListResponse
  - `data` Agent[], required — List of agents matching the filter criteria.
    - `id` string, required — System-generated unique identifier for the agent.
    - `name` string, required — Human-readable name for the agent.
    - `customerId` string, required — The ID of the customer this agent operates on behalf of.
    - `isPaused` boolean, required — Whether the agent is currently paused. Paused agents cannot initiate any actions.
    - `isConnected` boolean, required — Whether the agent has been installed and connected (i.e., its device code has been redeemed).
    - `policy` AgentPolicy, required — Policy governing what an agent can do, how it executes actions, and its spending boundaries.
      - `permissions` AgentPermission[], required — List of permissions granted to the agent.
      - `defaultExecutionMode` 'AUTO' | 'APPROVAL_REQUIRED', required — 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.
      - `spendingLimits` AgentSpendingLimits, required — 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.
        - `currency` string, required — ISO 4217 currency code that all amount limits are denominated in.
        - `perTransactionLimit` integer, required — Maximum amount the agent can transfer in a single transaction.
        - `dailyLimit` integer, nullable — Maximum total amount the agent can transfer per day. Null means no daily limit.
        - `dailyTransactionLimit` integer — Maximum number of transactions the agent can initiate per day.
        - `monthlyLimit` integer, nullable — Maximum total amount the agent can transfer per month. Null means no monthly limit.
      - `accountRestrictions` AgentAccountRestrictions — Optional restrictions that limit the agent to specific accounts or override policy per account.
        - `allowedAccountIds` string[], nullable — If set, restricts the agent to operate only on the specified internal account IDs. Null means the agent can access all accounts.
        - `accountRules` AgentAccountRule[] — Per-account rules that override the agent's default policy for specific accounts.
          - `accountId` string, required — The internal account ID this rule applies to.
          - `executionMode` 'AUTO' | 'APPROVAL_REQUIRED' — 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.
          - `perTransactionLimit` integer, nullable — Per-transaction limit override, in the smallest unit of the relevant currency. Null inherits from the agent's spending limits.
      - `approvalThresholds` AgentApprovalThresholds — 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.
        - `currency` string — ISO 4217 currency code that the amount threshold is denominated in. Required when amount is set.
        - `amount` integer, nullable — 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.
    - `usage` AgentUsage, required — Real-time counters tracking the agent's spending and transaction activity against its policy limits.
      - `dailyTransactionCount` integer, required — Number of transactions initiated by the agent today.
      - `dailySpend` integer, required — Total amount spent by the agent today, in the smallest unit of the policy's `spendingLimits.currency`.
      - `dailyResetDate` string, date — The date when daily usage counters will reset.
      - `monthlySpend` integer, required — Total amount spent by the agent this month, in the smallest unit of the policy's `spendingLimits.currency`.
      - `monthlyResetMonth` string — The year-month (YYYY-MM) when monthly usage counters will reset.
    - `createdAt` string, date-time, required — Creation timestamp.
    - `updatedAt` string, date-time, required — Last update timestamp.
  - `hasMore` boolean, required — Indicates if more results are available beyond this page.
  - `nextCursor` string — Cursor to retrieve the next page of results (only present if hasMore is true).
  - `totalCount` integer — Total number of agents matching the criteria (excluding pagination).

## Other responses

- `400` — Bad request - Invalid parameters
- `401` — Unauthorized
- `500` — Internal service error

---

[API](https://skmtc.net/lightsparkdev/apis/grid-api.md) · [All operations](https://skmtc.net/lightsparkdev/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lightsparkdev/grid-api/versions/d0bce562bffd/schema)