Get a payout run

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs/{payoutRunId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs/{payoutRunId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs/{payoutRunId}")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build()

val response = client.newCall(request).execute()

{
  "id": "PayoutRun:019542f5-b3e7-1d02-0000-000000000001",
  "status": "VALIDATING",
  "source": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "allOrNothing": false,
  "rowCounts": {
    "total": 1000,
    "pending": 0,
    "pendingClaim": 12,
    "processing": 0,
    "completed": 980,
    "failed": 8,
    "skipped": 0
  },
  "createdAt": "2026-11-04T22:00:00Z",
  "updatedAt": "2026-11-05T02:14:00Z",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "agentActionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
  "total": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "rowCount": 12,
  "scheduledAt": "2026-11-05T02:00:00Z",
  "finishedAt": "2026-11-05T02:14:00Z"
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

GET

agents

payout-runs

{payoutRunId}

Get a payout run

curl --request GET \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs/{payoutRunId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs/{payoutRunId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs/{payoutRunId}")
  .get()
  .addHeader("Authorization", "Bearer <token>")
  .build()

val response = client.newCall(request).execute()

{
  "id": "PayoutRun:019542f5-b3e7-1d02-0000-000000000001",
  "status": "VALIDATING",
  "source": {
    "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001"
  },
  "allOrNothing": false,
  "rowCounts": {
    "total": 1000,
    "pending": 0,
    "pendingClaim": 12,
    "processing": 0,
    "completed": 980,
    "failed": 8,
    "skipped": 0
  },
  "createdAt": "2026-11-04T22:00:00Z",
  "updatedAt": "2026-11-05T02:14:00Z",
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "agentActionId": "AgentAction:019542f5-b3e7-1d02-0000-000000000099",
  "total": {
    "amount": 12550,
    "currency": {
      "code": "USD",
      "name": "United States Dollar",
      "symbol": "$",
      "decimals": 2
    }
  },
  "rowCount": 12,
  "scheduledAt": "2026-11-05T02:00:00Z",
  "finishedAt": "2026-11-05T02:14:00Z"
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

Bearer token authentication for agent-scoped endpoints. The token is the accessToken returned when redeeming a device code via POST /agents/device-codes/redeem. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy.

Path Parameters

payoutRunId

string

required

System-generated unique payout run identifier

Response

Successful operation

A payout run an agent created. allOrNothing is always false, and scheduledAt is never set.

string

required

System-generated unique payout run identifier

Example:

"PayoutRun:019542f5-b3e7-1d02-0000-000000000001"

status

enum<string>

required

Status of a payout run.

Status	Description
`VALIDATING`	Grid is validating the rows. No row is paid yet.
`PENDING_APPROVAL`	An agent's run waiting for the customer to approve its `PAYOUT_RUN` action. No row is paid yet. Approving it makes the run `PROCESSING`; rejecting it, or letting it expire, makes it `CANCELLED`.
`SCHEDULED`	Accepted, waiting for `scheduledAt`.
`PROCESSING`	Rows are being paid.
`COMPLETED`	Every accepted row completed or is held for a claim, and none failed.
`PARTIALLY_FAILED`	At least one row completed or is held for a claim, and at least one failed.
`FAILED`	No row completed or is held for a claim.
`CANCELLED`	Cancelled. Rows that had not started are `SKIPPED`.

Available options:

VALIDATING,

PENDING_APPROVAL,

SCHEDULED,

PROCESSING,

COMPLETED,

PARTIALLY_FAILED,

FAILED,

CANCELLED

source

object

required

Show child attributes

allOrNothing

boolean

required

Example:

false

rowCounts

object

required

Show child attributes

createdAt

string<date-time>

required

Example:

"2026-11-04T22:00:00Z"

updatedAt

string<date-time>

required

Example:

"2026-11-05T02:14:00Z"

agentId

string

required

The agent that created the run.

Example:

"Agent:019542f5-b3e7-1d02-0000-000000000042"

agentActionId

string

required

The run's PAYOUT_RUN agent action, which the customer approves or rejects when the run needs approval.

Example:

"AgentAction:019542f5-b3e7-1d02-0000-000000000099"

total

object

required

The sum of the rows' amounts, in the source account's currency. This is what leaves the wallet if every row is paid.

Show child attributes

rowCount

integer

required

How many rows the run has.

Example:

12

scheduledAt

string<date-time>

When the run starts paying rows, if it was scheduled.

Example:

"2026-11-05T02:00:00Z"

finishedAt

string<date-time>

When the run reached COMPLETED, PARTIALLY_FAILED, FAILED or CANCELLED.

Example:

"2026-11-05T02:14:00Z"

Using the API

API documentation

Get a payout run

Authorizations

Path Parameters

Response