Get an agent action
Retrieve a specific action submitted by the authenticated agent. Poll this endpoint after submitting an action that requires approval to check whether it has been approved, rejected, or has failed.
Authorizations
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
Unique identifier of the agent action
Response
Successful operation
An action submitted by an agent that may require platform approval before execution. All agent-initiated operations (quote execution, transfers) are represented as AgentActions, giving the platform a consistent object to approve, reject, and audit regardless of the underlying operation type.
System-generated unique identifier for this action.
"AgentAction:019542f5-b3e7-1d02-0000-000000000099"
The agent that submitted this action.
"Agent:019542f5-b3e7-1d02-0000-000000000042"
The customer on whose behalf the action was submitted.
"Customer:019542f5-b3e7-1d02-0000-000000000010"
Platform-specific ID of the customer.
"user-a1b2c3"
Status of an agent action.
PENDING_APPROVAL, APPROVED, REJECTED, FAILED The type of action the agent is requesting.
EXECUTE_QUOTE, ISSUE_PURCHASE_CARD, CLAIMABLE_PAYOUT, USE_STORED_CARD, CREATE_SETTLEMENT_RULE, UPDATE_SETTLEMENT_RULE, PAYOUT_RUN When the action expires. For an EXECUTE_QUOTE action with priceTolerance, this is the end of the platform's approval window, independent of the quote's own expiry: approval executes a live quote and quotes the send again once it has expired, and a pending action that reaches this time fails with APPROVAL_EXPIRED. For any other EXECUTE_QUOTE action, this is the quote's own expiry; a pending action that reaches it fails with QUOTE_EXPIRED, and approval never creates a replacement quote. For ISSUE_PURCHASE_CARD, USE_STORED_CARD, CREATE_SETTLEMENT_RULE, UPDATE_SETTLEMENT_RULE and PAYOUT_RUN, this is the end of the approval window, after which a pending action fails with APPROVAL_EXPIRED; a settlement rule's window is seven days, and a payout run's 24 hours.
"2025-10-03T15:05:00Z"
When the action was submitted by the agent.
"2025-10-03T15:00:00Z"
When the action was last updated.
"2025-10-03T15:02:00Z"
The quote being executed. Contains the full amount, currency, destination, and rate details needed to present an approval decision to the user. Present for EXECUTE_QUOTE.
The quote the customer was shown before an approval found that the price had moved past priceTolerance. Present only while the action is PENDING_APPROVAL after such an approval; quote is then the new quote to show the customer, and approving it again repeats the check against it.
Present on a PENDING_APPROVAL EXECUTE_QUOTE action that Grid quotes again when it is approved after its quote expired: how far the price may move against the customer before they are asked again. Fixed when the action is created. Absent when approval can only execute quote as it is.
The purchase card the agent asked for, so an approval decision can show its amount, limit, description and funding account. Present for ISSUE_PURCHASE_CARD.
The claimable payout the agent asked to send, so an approval decision can show its amount and recipient. Present for CLAIMABLE_PAYOUT. Approving the action makes the payout AWAITING_CLAIM; rejecting it, or letting it expire, ends the payout and releases its hold.
The stored card the agent asked to use, where, and for how much, so an approval decision can show them. Present for USE_STORED_CARD. Approving the action lets the agent collect a single-use link with POST /agents/me/stored-cards/{storedCardId}/reveal and actionId.
The settlement rule the agent proposed, so an approval decision can show what it matches, who it pays and its limits. Present for CREATE_SETTLEMENT_RULE and UPDATE_SETTLEMENT_RULE. For CREATE_SETTLEMENT_RULE, approving the action makes the rule ACTIVE; rejecting it, or letting it expire, deletes it. For UPDATE_SETTLEMENT_RULE, it is the rule as the change would make it, with the rule's id; approving the action applies the change, and rejecting it, or letting it expire, drops it while the rule keeps its terms. Approving a rule does not approve its payments in advance. Each share is still checked against the agent's policy when it is sent.
The payout run the agent created, so an approval decision can show every row. Present for PAYOUT_RUN. Approving the action starts the run; rejecting it, or letting it expire, cancels the run and skips every row. The approval covers each row's own approval, so no row waits for another.
The purchase card the action issued, or for an increase the card whose amount it raised. Present for an ISSUE_PURCHASE_CARD action once it is APPROVED and the card is issued or increased; read it with GET /agents/me/cards/{cardId}.
"Card:019542f5-b3e7-1d02-0000-000000000011"
The resulting transaction, populated once the action has been approved and execution has begun. Absent while the action is PENDING_APPROVAL or REJECTED.
- Incoming Transaction
- Outgoing Transaction
- Card Transaction
Human-readable reason provided by the platform when rejecting the action. Only present when status is REJECTED.
"Transaction amount exceeds customer's current risk limit."
Machine-readable reason the action failed. Only present when status is FAILED; rejectionReason is used only for REJECTED actions.
QUOTE_EXPIRED, POLICY_DENIED, AGENT_INACTIVE, EXECUTION_FAILED, PRICE_MOVED, ADDRESS_REFUSED, APPROVAL_EXPIRED, DELETED_BY_AGENT, AGENT_CANCELLED