---
title: "List customers"
method: GET
path: "/customers"
tags: ["Customers"]
---

# List customers

`GET /customers`

List customers who have authorized an agent to act for them

## Query parameters

- `cursor` string — Cursor from the previous page.
- `limit` integer — Maximum results per page.
- `status` 'active' | 'revoked' | 'all' — Filter by connection state. Active returns any non-revoked connection (including suspended and expired). Revoked returns customers whose access was revoked. All returns both.

## Headers

- `X-Agent-ID` string, nullable
- `X-Instance-ID` string, nullable

## Response `200`

Successful Response

- object
  - `data` object[], required
    - `type` 'customer', required
    - `id` string, required — Customer party ID (pty_*).
    - `attributes` object, required
      - `name` string, required — Customer name.
      - `email` string, nullable, required — Email address.
      - `avatarUrl` string, uri, nullable, required — Public avatar URL, or null if none is set.
      - `createdAt` string, date-time, nullable, required — When the customer was created.
      - `delegation` object, required — Delegation details.
        - `id` string, required — Delegation ID (dlg_*).
        - `status` 'ACTIVE' | 'SUSPENDED' | 'REVOKED' | 'EXPIRED', required — Delegation status.
        - `permissions` string[], required — Granted permissions.
        - `createdAt` string, date-time, required — When the customer was connected.
        - `revokedAt` string, date-time, nullable, required — When access was revoked, or null if not revoked.
      - `agents` object[], required — Connected agents.
        - `id` string, required — Agent ID (agt_*).
        - `name` string, nullable, required — Agent name.
        - `handle` string, nullable, required — The agent's composed public handle (@namespace-slug), or null when it has none.
        - `status` string, required — Connection status.
        - `permissions` string[], required — Permissions this agent holds.
        - `limits` object, nullable, required — Spending limits in cents (per-transaction, daily, monthly) for this agent.
          - `perTransaction` integer, nullable — Per-transaction spending limit in cents, or null for no limit.
          - `perDay` integer, nullable — Daily spending limit in cents, or null for no limit.
          - `perMonth` integer, nullable — Monthly spending limit in cents, or null for no limit.
  - `meta` object, required
    - `pagination` object, required
      - `hasMore` boolean, required — Whether more results are available.
      - `nextCursor` string, nullable, required — Cursor for the next page, or null when there are no more results.

## Other responses

- `400` — Validation Error
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found. Returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
- `409` — Conflict
- `422` — Validation Error
- `428` — Precondition Required
- `429` — Too Many Requests
- `500` — Internal Server Error
- `501` — Not Implemented
- `502` — Bad Gateway
- `503` — Service Unavailable

---

[API](https://skmtc.net/natural/apis/natural-api.md) · [All operations](https://skmtc.net/natural/apis/natural-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/natural/natural-api/versions/0bb9c54b1f61/schema)