> ## Documentation Index > Fetch the complete documentation index at: https://agents-docs.lightspark.com/llms.txt > Use this file to discover all available pages before exploring further. # List Transactions > Query and filter payment history with powerful filtering and pagination options Retrieve transaction history with flexible filtering options. Transactions are returned in descending order (most recent first) with a default limit of 20 per page. ```bash cURL theme={null} curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions' \ -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" { "data": [ { "id": "Transaction:019542f5-b3e7-1d02-0000-000000000030", "status": "COMPLETED", "type": "OUTGOING", "direction": "DEBIT", "source": { "accountId": "InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965", "currency": "USD" }, "destination": { "accountId": "ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123", "currency": "EUR" }, "sentAmount": { "amount": 10000, "currency": { "code": "USD", "symbol": "$", "decimals": 2 } }, "receivedAmount": { "amount": 9200, "currency": { "code": "EUR", "symbol": "€", "decimals": 2 } }, "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001", "platformCustomerId": "customer_12345", "description": "Payment for services - Invoice #1234", "exchangeRate": 0.92, "settledAt": "2025-10-03T15:30:00Z", "createdAt": "2025-10-03T15:00:00Z" } ], "hasMore": true, "nextCursor": "eyJpZCI6IlRyYW5zYWN0aW9uOjAxOTU0MmY1LWIzZTctMWQwMi0wMDAwLTAwMDAwMDAwMDAzMCJ9", "totalCount": 45 } ``` ## Filtering transactions Use query parameters to filter and narrow down transaction results. ### Filter by customer Get all transactions for a specific customer: ```bash theme={null} curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?customerId=Customer:019542f5-b3e7-1d02-0000-000000000001' \ -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" ``` Or use your platform's customer ID: ```bash theme={null} curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?platformCustomerId=customer_12345' \ -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" ``` ### Filter by transaction type Get only incoming or outgoing transactions. A transaction's type is keyed on its destination — anything landing in an internal account is `INCOMING`, and anything landing in an external account or at a UMA address is `OUTGOING`. See [Transaction Lifecycle](https://agents-docs.lightspark.com/platform-overview/core-concepts/transaction-lifecycle.md#incoming-or-outgoing) for the full table. > [tab] Outgoing Only > > ```bash theme={null} > curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?type=OUTGOING' \ > -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" > ``` > [tab] Incoming Only > > ```bash theme={null} > curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?type=INCOMING' \ > -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" > ``` ### Filter by status Get transactions in a specific status: ```bash theme={null} # Get all pending transactions curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?status=PENDING' \ -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" # Get all completed transactions curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?status=COMPLETED' \ -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" ``` **Available statuses:** * `PENDING` - Transaction initiated, awaiting processing * `PROCESSING` - Transaction in progress * `COMPLETED` - Transaction successfully completed * `FAILED` - Transaction failed * `EXPIRED` - Quote expired before execution ### Filter by date range Get transactions within a specific date range: ```bash theme={null} curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?startDate=2025-10-01T00:00:00Z&endDate=2025-10-31T23:59:59Z' \ -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" ``` > [!TIP] > > Dates must be in ISO 8601 format (e.g., `2025-10-03T15:00:00Z`). ### Filter by account Get transactions for a specific account: ```bash theme={null} # Any transactions involving this account (sent or received) curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?accountIdentifier=InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965' \ -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" # Only transactions sent FROM this account curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?senderAccountIdentifier=InternalAccount:e85dcbd6-dced-4ec4-b756-3c3a9ea3d965' \ -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" # Only transactions sent TO this account curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?receiverAccountIdentifier=ExternalAccount:a12dcbd6-dced-4ec4-b756-3c3a9ea3d123' \ -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" ``` ## Combining filters You can combine multiple filters to narrow down results: ```bash theme={null} # Get completed outgoing transactions for a customer in October 2025 curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?customerId=Customer:019542f5-b3e7-1d02-0000-000000000001&type=OUTGOING&status=COMPLETED&startDate=2025-10-01T00:00:00Z&endDate=2025-10-31T23:59:59Z' \ -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" ``` ## Pagination Handle large result sets with cursor-based pagination: **1. Get first page** ```bash theme={null} curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?limit=20' \ -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" ``` Response: ```json theme={null} { "data": [ /* 20 transactions */ ], "hasMore": true, "nextCursor": "eyJpZCI6IlRyYW5z...", "totalCount": 150 } ``` **2. Get next page** Use the `nextCursor` from the previous response: ```bash theme={null} curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions?limit=20&cursor=eyJpZCI6IlRyYW5z...' \ -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" ``` **3. Continue until done** Keep paginating while `hasMore` is `true`: ```javascript theme={null} async function getAllTransactions() { const allTransactions = []; let cursor = null; let hasMore = true; while (hasMore) { const url = cursor ? `https://api.lightspark.com/grid/2025-10-13/transactions?limit=100&cursor=${cursor}` : `https://api.lightspark.com/grid/2025-10-13/transactions?limit=100`; const response = await fetch(url, { headers: { Authorization: `Basic ${credentials}` }, }); const { data, hasMore: more, nextCursor } = await response.json(); allTransactions.push(...data); hasMore = more; cursor = nextCursor; } return allTransactions; } ``` > [!NOTE] > > The maximum `limit` is 100 transactions per request. Default is 20. ## Get a single transaction Retrieve details for a specific transaction by ID: ```bash theme={null} curl -X GET 'https://api.lightspark.com/grid/2025-10-13/transactions/Transaction:019542f5-b3e7-1d02-0000-000000000030' \ -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" ``` ## Best practices > [accordion] Use pagination for large datasets > > Always implement pagination when fetching transactions to avoid timeouts and memory issues: > > ```javascript theme={null} > // Good: Paginated approach > async function fetchWithPagination(filters) { > const transactions = []; > let cursor = null; > > do { > const page = await fetchTransactionPage(filters, cursor); > transactions.push(...page.data); > cursor = page.nextCursor; > } while (cursor); > > return transactions; > } > > // Bad: Trying to fetch everything at once > async function fetchAll() { > const response = await fetch("/transactions?limit=10000"); // Don't do this! > return response.json(); > } > ``` > [accordion] Cache results when appropriate > > For data that doesn't change frequently (like completed transactions), implement caching: > > ```javascript theme={null} > const cache = new Map(); > > async function getCompletedTransactions(customerId, month) { > const cacheKey = `${customerId}-${month}`; > > if (cache.has(cacheKey)) { > return cache.get(cacheKey); > } > > const transactions = await fetchMonthlyTransactions(customerId, month); > cache.set(cacheKey, transactions); > > return transactions; > } > ``` > [accordion] Use specific filters to reduce result sets > > Apply filters to get only the data you need: > > ```javascript theme={null} > // Good: Specific filters > const recentFailed = await fetch( > "/transactions?status=FAILED&startDate=2025-10-01T00:00:00Z&type=OUTGOING" > ); > > // Bad: Fetch everything and filter in code > const all = await fetch("/transactions"); > const filtered = all.data.filter( > (tx) => > tx.status === "FAILED" && > tx.type === "OUTGOING" && > new Date(tx.createdAt) > new Date("2025-10-01") > ); > ``` > [accordion] Handle rate limits gracefully > > Implement exponential backoff for rate limit errors: > > ```javascript theme={null} > async function fetchWithRetry(url, retries = 3) { > for (let i = 0; i < retries; i++) { > const response = await fetch(url, { > headers: { Authorization: `Basic ${credentials}` }, > }); > > if (response.status === 429) { > const retryAfter = parseInt( > response.headers.get("Retry-After") || "1", > 10 > ); > await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000)); > continue; > } > > return response.json(); > } > > throw new Error("Max retries exceeded"); > } > ``` ## Next steps ![](https://agents-docs.lightspark.com/images/icons/paper-plane-top-right.svg) Send Payments Learn how to send payments from internal accounts [Open](https://agents-docs.lightspark.com/payouts-and-b2b/payment-flow/send-payment.md) ![](https://agents-docs.lightspark.com/images/icons/receipt-check.svg) Reconciliation Match payments with your internal accounting systems [Open](https://agents-docs.lightspark.com/payouts-and-b2b/payment-flow/reconciliation.md) ![](https://agents-docs.lightspark.com/images/icons/square-info.svg) Error Handling Handle transaction failures and errors [Open](https://agents-docs.lightspark.com/payouts-and-b2b/payment-flow/error-handling.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.