List agents

Retrieve a paginated list of agents for the authenticated platform.

GET /agents

cURL

cURL

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/agents \
  --header 'Authorization: Basic <encoded-value>'

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);
}

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()
}

200

{
  "data": [
    {
      "id": "Agent:019542f5-b3e7-1d02-0000-000000000001",
      "name": "Payroll Automation Agent",
      "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
      "isPaused": false,
      "isConnected": true,
      "policy": {
        "permissions": [],
        "spendingLimits": {
          "currency": "USD",
          "perTransactionLimit": 50000,
          "dailyLimit": 500000,
          "dailyTransactionLimit": 10,
          "monthlyLimit": 5000000
        },
        "accountRestrictions": {
          "allowedAccountIds": [
            "Account:019542f5-b3e7-1d02-0000-000000000001"
          ],
          "accountRules": [
            {
              "accountId": "Account:019542f5-b3e7-1d02-0000-000000000001",
              "perTransactionLimit": 10000
            }
          ]
        },
        "approvalThresholds": {
          "currency": "USD",
          "amount": 100000
        }
      },
      "usage": {
        "dailyTransactionCount": 3,
        "dailySpend": 150000,
        "monthlySpend": 750000,
        "dailyResetDate": "2025-07-22",
        "monthlyResetMonth": "2025-08"
      },
      "createdAt": "2025-07-21T17:32:28Z",
      "updatedAt": "2025-07-21T17:32:28Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "<string>",
  "totalCount": 123
}

{
  "status": 400,
  "message": "<string>",
  "details": {}
}

{
  "status": 401,
  "message": "<string>",
  "details": {}
}

{
  "status": 500,
  "message": "<string>",
  "details": {}
}

Authorizations

Authorization · string · header · required

API token authentication using format <api token id>:<api client secret>

Query Parameters

customerId · string

Filter by customer ID

isPaused · boolean

Filter by paused status

isConnected · boolean

Filter by connection status (whether the device code has been redeemed)

createdAfter · string<date-time>

Filter agents created after this timestamp (inclusive)

createdBefore · string<date-time>

Filter agents created before this timestamp (inclusive)

updatedAfter · string<date-time>

Filter agents updated after this timestamp (inclusive)

updatedBefore · string<date-time>

Filter agents updated before this timestamp (inclusive)

limit · integer · default: 20

Maximum number of results to return (default 20, max 100)

Required range: 1 <= x <= 100

cursor · string

Cursor for pagination (returned from previous request)

Response

200

application/json

Successful operation

data · object[] · required

List of agents matching the filter criteria.

Show child attributes

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).