> ## Documentation Index > Fetch the complete documentation index at: https://docs.dakota.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Get the customer's account insight report (BETA) > > **Beta** — early access. A deterministic, read-only report over the customer's agentic activity: a snapshot of typed facts (funding-wallet balances, upcoming totals, open payments, active mandates), observations (`insights`), and advisory recommendations (`suggestions`). Observations and suggestions share one item schema — `{kind, severity, message, detail, evidence}` — and every item carries `evidence`: typed references to the platform objects it was computed from. `kind` is an OPEN set; clients must ignore kinds they do not recognize. Every number is computed server-side; nothing here moves money or changes state. ## OpenAPI ````yaml /openapi.yaml get /customers/{customer_id}/insights openapi: 3.0.3 info: title: Dakota Platform API version: 1.0.0 description: >- Combined API specification for Dakota Platform services: - Issuance API: Asset minting and burning operations - Onboarding API: Know Your Business/Customer verification - On/Off Ramp API: Managing on-ramp and off-ramp accounts - Recipients API: Managing destinations for KYB'd entities - Transactions API: Viewing transaction history across platform operations ## Authentication and API Headers All API endpoints require the following headers: - `x-idempotency-key`: Required for all POST endpoints to ensure request idempotency - `x-api-key`: Required for authentication across all endpoints Note: On /applications endpoints you need a token for authentication instead of a x-api-key - `x-application-token`: Required for authentication on public /applications endpoints (alternative to `x-api-key` where documented) ## Rate Limits Requests are rate limited per API key. Every response includes the following headers: | Header | Description | | --- | --- | | `X-RateLimit-Limit` | Maximum requests allowed in the current one-minute window. | | `X-RateLimit-Remaining` | Requests remaining in the current window. | | `X-RateLimit-Reset` | Absolute Unix timestamp (seconds since epoch) when the current rate-limit window resets. | When a request is throttled (`429`), responses also include `Retry-After` with seconds to wait before retrying. servers: - url: https://api.platform.dakota.xyz description: Production environment - url: https://api.platform.sandbox.dakota.xyz description: Sandbox — safe for testing with simulated data security: - ApiKeyAuth: [] tags: - name: Agentic Payments x-beta: true description: >- Beta — agent-driven payments: provision agents, draft and approve spending mandates, accept reviewed instructions, and manage scheduled payments. **Prerequisites:** Customer onboarded; signer groups attached for recognition. **Related:** Wallets, Signer Groups, Transactions - name: Mandates x-beta: true description: >- Beta — spending mandates: signed, signer-bound authorizations governing what may be spent, approved or cancelled by a second recognized signer (§8 — the dual-control rule that every mandate mutation must be signed by a recognized signer OTHER than the bound one). Independent of agents and scheduled payments. **Prerequisites:** Signer groups attached for recognition. **Related:** Signer Groups, Transactions - name: Insights x-beta: true description: >- Beta — read-only account insight: a deterministic report over a customer's agentic activity (funding balances, upcoming obligations, failures, mandate headroom and expiry). Never moves money, never creates or changes anything. **Prerequisites:** Customer onboarded; insight is computed from the customer's scheduled payments, mandates, and wallets. **Related:** Agentic Payments, Mandates - name: Customers description: >- Manage customer entities representing businesses and organizations onboarded to Dakota. **Prerequisites:** Complete KYB via Onboarding endpoints before initiating money movement. **Related:** Onboarding, Recipients, Transactions, Accounts, Wallets - name: Wallets description: >- Manage wallets, balances, and wallet-to-signer-group relationships for custody and movement controls. **Prerequisites:** Customer must exist. Configure signer groups before policy-enforced workflows. **Related:** Signer Groups, Policies, Transactions, Customers - name: Transactions description: >- Create, cancel, and retrieve transaction records across account and wallet flows. **Prerequisites:** Accounts or destinations must be configured based on flow type. **Related:** Accounts, Recipients, Policies, Events - name: Recipients description: >- Manage recipient entities and destination rails used by customers for payouts and transfers. **Prerequisites:** Customer must be onboarded and active. **Related:** Customers, Transactions, Accounts, Onboarding - name: Accounts description: >- Manage account resources used for onramp, offramp, and swap operations. **Prerequisites:** Customer must be created and network/asset constraints must be known. **Related:** Customers, Transactions, Auto Transactions, Info - name: Auto Transactions description: >- Manage automated transaction configurations and execution history for account automation workflows. **Prerequisites:** Source account must exist and be configured for automation. **Related:** Accounts, Transactions, Events - name: Onboarding description: >- Manage KYB/KYC onboarding lifecycle, application documents, attestations, and verification steps. **Prerequisites:** Customer context and required entity/application metadata. **Related:** Customers, Exceptions, Recipients, Transactions - name: Policies description: >- Define and manage policy objects and rules used for transaction governance and risk controls. **Prerequisites:** Wallet and signer group resources should be configured for enforcement scenarios. **Related:** Wallets, Signer Groups, Transactions - name: Signer Groups description: >- Manage signer groups and signer assignments for multi-party authorization models. **Prerequisites:** Wallets should exist before linking signer groups. **Related:** Wallets, Policies, Transactions - name: Authentication description: >- Manage API authentication credentials and key lifecycle for platform access. **Prerequisites:** Client organization must be provisioned. **Related:** Users, Info - name: Users description: >- Manage client users, roles, and identity metadata for platform access control. **Prerequisites:** Auth credentials and client context must be established. **Related:** Authentication - name: Webhooks description: >- Manage outbound webhook targets and delivery configuration for event notifications. **Prerequisites:** Subscriber endpoint must be reachable and secured. **Related:** Events, Authentication - name: Payouts description: >- Manage where Dakota sends your accrued developer-fee payouts. **Prerequisites:** Auth credentials and client context must be established. **Related:** Events - name: Events description: >- Retrieve event records emitted by platform operations for audit and troubleshooting. **Prerequisites:** Requesting client must have access to referenced resources. **Related:** Webhooks, Transactions, Onboarding - name: Info description: >- Read platform capability metadata, such as supported rails, networks, and assets. These operations are served under `/capabilities/*` - `GET /capabilities/countries` and `GET /capabilities/networks`. The tag name does not appear in the request paths. **Prerequisites:** Valid authentication headers. **Related:** Accounts, Transactions - name: Sandbox description: >- Trigger sandbox-only simulation endpoints for safe end-to-end integration testing with synthetic data. The sandbox host (`https://api.platform.sandbox.dakota.xyz`) also accepts a family of `X-Sandbox-*` request headers on most write endpoints (`Customers`, `Accounts`, `Transactions`, simulate endpoints) that let integrators drive deterministic failure modes — pick a preset via `X-Sandbox-Scenario`, or compose a custom one with `X-Sandbox-Error-Step`/`X-Sandbox-Error-Status`/`X-Sandbox-Error-Message`. `X-Sandbox-Instant-Completion` collapses async flows to a single synchronous step, and `X-Sandbox-Skip-Auto-Approval` keeps newly created KYB applications in `pending` for manual-review testing. All `X-Sandbox-*` headers are ignored in production. **Prerequisites:** Sandbox environment and test customer data. **Related:** Customers, Accounts, Transactions, Onboarding - name: Legal description: |- The legal documents customers accept — terms of service, privacy policy, e-sign notice, and partner agreements. Dakota publishes these here, and this is the authoritative source: the hosted onboarding flow, the dakota.xyz website, and your own integration all read the same revisions. Present the current revision to your customer before capturing their acceptance so the record reflects the text they actually saw. paths: /customers/{customer_id}/insights: get: tags: - Insights summary: Get the customer's account insight report (BETA) description: > > **Beta** — early access. A deterministic, read-only report over the customer's agentic activity: a snapshot of typed facts (funding-wallet balances, upcoming totals, open payments, active mandates), observations (`insights`), and advisory recommendations (`suggestions`). Observations and suggestions share one item schema — `{kind, severity, message, detail, evidence}` — and every item carries `evidence`: typed references to the platform objects it was computed from. `kind` is an OPEN set; clients must ignore kinds they do not recognize. Every number is computed server-side; nothing here moves money or changes state. operationId: getCustomerInsights parameters: - name: customer_id in: path required: true schema: type: string responses: '200': description: The customer's insight report content: application/json: schema: $ref: '#/components/schemas/InsightReport' example: customer_id: 2vWxCustomer0000000000000000 generated_at: 1783075200 snapshot: total_usd: '3100.25' balances: - wallet_id: 2vWxWallet000000000000000000 name: Operating network_id: base-mainnet asset: USDC amount_usd: '3100.25' upcoming: days: 14 count: 3 totals: USDC: '5200' open_scheduled_payments: 5 active_mandates: 2 insights: - kind: upcoming_payments severity: info message: 3 payment(s) scheduled in the next 14 days (5200 USDC). detail: count: 3 window_days: 14 evidence: - type: scheduled_payment id: 2vWxPayment00000000000000000 suggestions: - kind: funding_shortfall severity: critical message: >- A funding wallet shows $3100.25 of USDC but 5200 USDC of payments fire from it on base-mainnet in the next 7 days — top up at least ~2099.75 USDC by 2026-07-14 or 3 payment(s) may fail. detail: wallet_id: 2vWxWallet000000000000000000 shortfall_estimate: '2099.75' evidence: - type: wallet id: 2vWxWallet000000000000000000 - type: scheduled_payment id: 2vWxPayment00000000000000000 '400': description: Invalid request content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: >- https://docs.dakota.xyz/api-reference/errors#invalid-identifier title: Invalid Identifier status: 400 detail: invalid customer id '404': description: Agentic payments not enabled, or the customer was not found content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' example: type: https://docs.dakota.xyz/api-reference/errors#not-found title: Not Found status: 404 detail: customer not found components: schemas: InsightReport: type: object required: - customer_id - generated_at - snapshot - insights - suggestions description: >- The deterministic, read-only insight report for a customer. Computed on demand; nothing is stored. properties: customer_id: type: string generated_at: type: integer format: int64 snapshot: $ref: '#/components/schemas/InsightSnapshot' insights: type: array items: $ref: '#/components/schemas/InsightItem' description: Observations about the account (always present, possibly empty). suggestions: type: array items: $ref: '#/components/schemas/InsightItem' description: >- Advisory recommendations (always present, possibly empty). Non-binding — acting on one is a separate, human-gated step. ProblemDetails: type: object required: - type - title - status description: | Error response following RFC 9457 Problem Details. Public API error responses use this format. example: type: https://docs.dakota.xyz/api-reference/errors#not-found title: Customer Not Found status: 404 detail: Customer cst_2abc123 was not found in your organization. instance: https://api.platform.dakota.xyz/customers/cst_2abc123 request_id: req_7f3a8b2c properties: type: type: string format: uri description: | URI reference identifying the problem type. Resolves to human-readable documentation. example: https://docs.dakota.xyz/api-reference/errors#not-found title: type: string description: >- Short, human-readable summary of the problem type. Stable across occurrences. example: Customer Not Found status: type: integer description: HTTP status code for this occurrence. example: 404 detail: type: string description: Human-readable explanation specific to this occurrence. example: Customer cst_2abc123 was not found in your organization. instance: type: string format: uri description: The request path that triggered this error. example: https://api.platform.dakota.xyz/customers/cst_2abc123 request_id: type: string description: Unique request identifier. Include when contacting support. example: req_7f3a8b2c errors: type: array description: Field-level validation errors (present for validation failures). items: $ref: '#/components/schemas/ValidationError' resolution_url: type: string format: uri description: | A link the customer can follow to CLEAR this error, present only on problems with a concrete self-service remedy. Today this is returned by `#terms-not-accepted`, where it points at the hosted flow in which the outstanding agreement can be signed. The link is token-gated and usable as-is — send the customer to it directly rather than parsing it out of `detail`. example: >- https://onboarding.dakota.xyz/applications/2abc123?token=tok_7f3a8b2c user_message: type: string description: | A plain-language rendition of `detail` written for the end customer, present when one exists for this error. `detail` names request fields and actions so a machine caller (such as a payment agent drafting proposals) can self-correct; `user_message` says the same thing without API vocabulary. Clients that relay errors into a human surface (chat, email, UI) should show `user_message` when present and fall back to `detail`. example: >- ACH payments pay out USD, so a USDC payout isn't possible on this rail. Change the payout currency to USD and try again. InsightSnapshot: type: object required: - upcoming - open_scheduled_payments - active_mandates description: > Typed FACTS about the account — rendered directly by clients, not narrated. `balances`/`total_usd` cover the wallets the customer's open payments spend from and are present only when the balance index is configured; they degrade to absent, never to an error. properties: total_usd: type: string balances: type: array items: $ref: '#/components/schemas/InsightSnapshotBalance' upcoming: $ref: '#/components/schemas/InsightSnapshotUpcoming' open_scheduled_payments: type: integer active_mandates: type: integer InsightItem: type: object required: - kind - severity - message - evidence description: > One observation (in `insights`) or advisory recommendation (in `suggestions`) — the same schema in both arrays. `kind` is an OPEN set: new kinds appear without notice and clients must ignore kinds they do not recognize. properties: kind: type: string description: > Machine-readable item type. This is an OPEN set — the values below are the kinds emitted TODAY, but new kinds may be added at any time without a breaking change, so it is documented as an extensible enum rather than a closed one. A client MUST render an unrecognized kind generically from `message` + `severity` (and `evidence`), never drop it. Kinds emitted today, by array: Observations (`insights[]`): * `upcoming_payments` — open payments due within the horizon (count + per-asset totals). * `payment_failures_clustered` — ≥2 recent failures to the same payee sharing one reason (root cause). * `payments_failed` — remaining recent singleton failures, summarized. * `account_activity` — executed volume over the window + mandates awaiting signature. * `new_counterparty` — first open payments to a recently-added payee. * `counterparty_concentration` — one payee dominates recent executed outflow. Suggestions (`suggestions[]`, advisory — acting is a separate human-gated step): * `payment_at_risk` — an open payment is past its scheduled time. * `funding_shortfall` — a funding wallet's indexed balance is below its near-term payment needs. * `mandate_expiring` — an active mandate ends soon (warn when open payments depend on it). * `mandate_headroom` — a mandate's window budget is nearly or already over-consumed. x-extensible-enum: - upcoming_payments - payment_failures_clustered - payments_failed - account_activity - new_counterparty - counterparty_concentration - payment_at_risk - funding_shortfall - mandate_expiring - mandate_headroom severity: type: string enum: - info - warn - critical message: type: string description: >- Human-readable, self-contained statement of the finding, with exact amounts and dates. detail: type: object additionalProperties: true description: >- Machine-readable facts behind the message (decimal strings, counts, unix timestamps). Keys vary by kind. evidence: type: array items: $ref: '#/components/schemas/InsightEvidence' description: >- The platform objects this item is computed from (capped; may be empty when the claim is an aggregate). ValidationError: type: object required: - field - message properties: field: type: string description: Field path using dot notation for nested fields. example: bank_account.routing_number message: type: string description: Human-readable description of the field error. example: Routing number must be exactly 9 digits code: type: string description: Machine-readable error code for this field. example: invalid_format InsightSnapshotBalance: type: object required: - wallet_id - network_id - asset - amount_usd description: >- One funding wallet's indexed holding of one asset on one network. The balance index prices holdings in USD; values may lag the chain. properties: wallet_id: type: string name: type: string network_id: type: string asset: type: string amount_usd: type: string InsightSnapshotUpcoming: type: object required: - days - count description: Open scheduled payments due within the window. properties: days: type: integer count: type: integer totals: type: object additionalProperties: type: string description: Asset → total amount due in the window (decimal strings). InsightEvidence: type: object required: - type - id description: >- One typed reference to the platform object an insight item was computed from. properties: type: type: string description: > Platform resource name — the kind of object `id` refers to. OPEN set (like `InsightItem.kind`): new resource types may be referenced without a breaking change, so a client MUST handle an unrecognized type gracefully (e.g. show the item without a deep-link), never error. `transaction` is reserved (advertised and client-handled, but not emitted today). x-extensible-enum: - wallet - scheduled_payment - mandate - recipient - transaction id: type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ````