> For the complete index of the 402pay docs, see [llms.txt](https://developer.402pay.co/llms.txt).

# Search

Find payments, customers and links with one query, best matches first.

`GET https://dash.402pay.co/api/v1/search`

One query across payments, customers and links, the way the dashboard's search works. Each result is the object itself, as its own endpoint returns it, so tell them apart by `kind`.

An exact ID, code, email, hash or address ranks first, then a word that starts with the query, then a match anywhere. Ties put links first, then customers, then payments, newest first within each. A restricted key searches only what it can read.

### Query

- `q` (string, required): Up to 100 characters. Payments match on their ID, checkout ID, reference, metadata values, transaction hash, sender address, description, customer name and email, and amount. Customers match on their ID, email and name, and links on their ID, code, name, description and price.
- `kind` (string): `payment`, `customer`, `link` or several, comma separated. Defaults to every kind the key can read.
- `include` (string): `customer` adds each payment's customer, as on [list payments](https://developer.402pay.co/api/payments/list.md).
- `limit` (integer): Page size, from 1 to 100. Defaults to 25.
- `cursor` (string): The `next_cursor` from the previous page. See [pagination](https://developer.402pay.co/api/pagination.md).

### Errors

- 400 `invalid_request` `q` is missing or too long, `kind` or `include` has a value it can't take, or the `cursor` belongs to another list.
- 403 `permission_denied` `kind` names something a restricted key can't read, `include=customer` was sent without read access to customers, or the key can read none of the three.

Any request can also fail on its key or its body. See [errors](https://developer.402pay.co/api/errors.md).

Request, cURL:

```bash
curl "https://dash.402pay.co/api/v1/search?q=harper&limit=1" \
  -H "Authorization: Bearer $PAY402_SECRET_KEY"
```

Request, Node.js:

```js
const response = await fetch("https://dash.402pay.co/api/v1/search?q=harper&limit=1", {
  headers: {
    Authorization: `Bearer ${process.env.PAY402_SECRET_KEY}`,
  },
});
const { data } = await response.json();
```

Request, Python:

```python
import os

import requests

response = requests.get(
    "https://dash.402pay.co/api/v1/search?q=harper&limit=1",
    headers={
        "Authorization": f"Bearer {os.environ['PAY402_SECRET_KEY']}",
    },
)
data = response.json()["data"]
```

Response, 200 OK:

```json
{
  "data": [
    {
      "id": "cst_gWFWcc7Ga0Pv7LSC",
      "kind": "customer",
      "name": "Harper Wilson",
      "email": "harper.wilson@example.com",
      "blocked": false,
      "note": "",
      "stats": {
        "payments_count": 2,
        "incomplete_count": 2,
        "volume": {
          "amount": 22810,
          "currency": "USD"
        },
        "average": {
          "amount": 11405,
          "currency": "USD"
        },
        "last_payment_at": "2026-09-26T21:22:47.082Z",
        "preferred_rail": "crypto"
      },
      "created_at": "2026-09-26T21:01:16.809Z",
      "updated_at": "2026-09-26T21:01:16.809Z"
    }
  ],
  "has_more": true,
  "next_cursor": "cst_gWFWcc7Ga0Pv7LSC"
}
```