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

# List customers

`GET /customers`

List customers who have delegated access to your agents.

## Query parameters

- `cursor` string — Cursor for pagination
- `limit` integer — Maximum number of results

## Headers

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

## Response `200`

Successful Response

- object
  - `data` object[], required
    - `type` 'customer', required — Resource type
    - `id` string, required — Customer party ID
    - `attributes` object, required — Customer attributes
      - `name` string, required — Customer name
      - `email` string, nullable, required — Email address
      - `avatarUrl` string, uri, nullable, required — Public avatar URL for this customer party, if one is set
      - `createdAt` string, date-time, nullable, required — When the customer was created
      - `delegation` object, required — Delegation details
        - `id` string, required — Delegation ID
        - `status` string, required — Delegation status
        - `permissions` string[], required — Granted permissions
        - `createdAt` string, date-time, required — When the customer was connected
      - `agents` object[], required — Connected agents
        - `id` string, required — Agent ID
        - `name` string, nullable, required — Agent name
        - `status` string, required — Connection status
        - `permissions` string[], required — Permissions this agent holds
        - `limits` TransactionLimits, required
          - `perTransaction` integer, nullable — Positive per-transaction limit in cents. null means no per-transaction limit.
  - `meta` object, required
    - `pagination` object, required
      - `hasMore` boolean, required
      - `nextCursor` string, nullable, required

## 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

## Changes

- **2026-07-14** `8cc2aed45847` — 1 info
  - added the required property `data/items/attributes/avatarUrl` to the response with the `200` status

[Change history](https://skmtc.dev/natural/apis/natural-api/changes/customers/get.md)

---

[API](https://skmtc.dev/natural/apis/natural-api.md) · [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/natural/natural-api/revisions/8cc2aed45847/schema)