Create a payout run

Pay up to 50 people at once from the agent’s customer’s stablecoin Embedded Wallet, in one approved action. Each row pays a contact by phone number or email, through a claimable payout, or one of the customer’s own ACTIVE external accounts, through a send. The run pays now: there is no schedule, and rows succeed or fail one by one.

Validation is all or nothing: a row the agent may not send, or a body Grid cannot read, refuses the whole request and creates nothing. A GRID_CUSTOMER row is refused with 400. A row paying an external account the agent may not pay is refused with DESTINATION_NOT_ALLOWED.

The run is checked against the agent’s policy as one payment of total: it needs the CREATE_QUOTES and EXECUTE_QUOTES permissions, and MANAGE_EXTERNAL_ACCOUNTS when a row pays a contact; total counts toward the spending limits as one transaction, and the spending pool is charged for bank payouts. A run the policy refuses is refused with AGENT_POLICY_DENIED. A run is created PROCESSING, with an APPROVED PAYOUT_RUN agent action, when the policy runs it without approval, the spending pool does not require approval and no row is above the platform’s limit for bank payouts without approval. Otherwise it is created PENDING_APPROVAL with a PENDING_APPROVAL PAYOUT_RUN action, and the AGENT_ACTION.PENDING_APPROVAL webhook fires. Approving the action starts the run. Rejecting it, or letting it expire after 24 hours, cancels the run and skips every row.

The customer’s approval of the run covers each row’s own approval. Each row is still checked when it is paid: the destination, the agent’s delegated key, the wallet’s free balance and sanctions screening. total is what leaves the wallet; a row’s fees come out of what its recipient receives.

Available only where the platform enables payout runs and agent payout runs, and claimable payouts for runs with a contact row.

POST /agents/me/payout-runs

Create a payout run

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/payout-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "sourceAccountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965",
  "rows": [
    {
      "clientRowId": "contractor-0042",
      "amount": 25000000,
      "destination": {
        "destinationType": "EXTERNAL_ACCOUNT",
        "externalAccountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123"
      },
      "description": "October invoice"
    }
  ]
}
'

201

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

Headers

Idempotency-Key · string · required

A unique identifier for the request, scoped to the agent. A retry with the same key and body returns the run the first request created; the same key with a different body is refused with 409.

Maximum string length: 255

Example:

"<uuid>"

Body

application/json

sourceAccountId · string · required

The customer's stablecoin Embedded Wallet that pays every row. It must hold an ACTIVE delegated key of this agent.

Example:

"InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965"

rows · object[] · required

The people to pay. Each pays a CONTACT or an EXTERNAL_ACCOUNT: one of the customer's own ACTIVE external accounts on the platform. A GRID_CUSTOMER row is refused.

Required array length: 1 - 50 elements

Show child attributes

Response

201

application/json

Payout run created, or the run this Idempotency-Key already created

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"