Get a payout run

Retrieve a payout run the authenticated agent created.

GET /agents/me/payout-runs/{payoutRunId}

Get a payout run

cURL

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

200

{
  "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"
}

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

200

application/json

Successful operation

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

id · 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"