> ## 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 (ALPHA) > > **Alpha** — 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-alpha: true description: >- Alpha — 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-alpha: true description: >- Alpha — 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-alpha: true description: >- Alpha — read-only account insight: a deterministic report over a customer's agentic activity (funding balances, upcoming obligations, failures, mandate headroom and expiry) plus an advisory chat that narrates it. 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. **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 paths: /customers/{customer_id}/insights: get: tags: - Insights summary: Get the customer's account insight report (ALPHA) description: > > **Alpha** — 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' 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 ````