# List counterparties

`GET /api/v1/counterparties`

Vendors, clients and contractors, newest first, with the row id breaking equal timestamps. Both the business's baseline payment limit and the current limit derived from the risk tier are reported. `performanceScore` is `null` when there is no history.

Send a [workspace API key](https://www.vestiarion.xyz/docs/get-started/authentication) as `Authorization: Bearer <key>`.

## Parameters

| Name | In | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `limit` | query | integer | Optional | `50` | 1 to 200 | How many items to return. Defaults to 50; a larger value is capped at 200. |
| `cursor` | query | string | Optional | — | — | The previous response's `page.nextCursor`, passed back unchanged to continue. Opaque: never decode or construct one. A cursor this endpoint could not have issued is refused with `400`. |
| `role` | query | string | Optional | — | `vendor`, `client`, `contractor` | Only counterparties with this role. |
| `riskLevel` | query | string | Optional | — | `unscreened`, `clear`, `medium`, `high` | Only counterparties at this risk tier. |

## Code samples

```bash
curl "https://www.vestiarion.xyz/api/v1/counterparties" \
  -H "Authorization: Bearer $VESTIARION_API_KEY"
```

## Response

Example, `200` `application/json`:

```json
{
  "data": [
    {
      "id": "dc5e5751-3287-46c9-8bd1-83a42ab02699",
      "name": "Anthropic API Services",
      "role": "vendor",
      "address": "0x90a5821e8a59b711777c49d11a283c9c76cd811e",
      "chain": "ARC-TESTNET",
      "jurisdiction": null,
      "riskLevel": "clear",
      "riskNotes": "No match against watchlist",
      "baselinePaymentLimit": 5,
      "paymentLimit": 5,
      "lastScreenedAt": "2026-09-24T18:32:57.327+00:00",
      "performanceScore": 0.667,
      "performanceInputs": {
        "heldOrFlagged": 0,
        "heldByOurPolicy": 1,
        "riskTierChanges": 0,
        "duplicateSubmissions": 0,
        "informationRequested": 0,
        "paidWithoutIntervention": 1
      },
      "createdAt": "2026-09-24T11:54:57.677284+00:00"
    }
  ],
  "page": {
    "nextCursor": "eyJrIjoiMjAyNi0wOS0yNFQxMTo1NDo1Ny42NzcyODQrMDA6MDAiLCJpZCI6ImRjNWU1NzUxLTMyODctNDZjOS04YmQxLTgzYTQyYWIwMjY5OSJ9",
    "hasMore": true,
    "count": 1
  }
}
```

**Fields**

- `data` (array of object, required)
  - `id` (string, required)
  - `name` (string, required)
  - `role` (string, required) One of `vendor`, `client`, `contractor`.
  - `address` (string, nullable, required)
  - `chain` (string, nullable, required)
  - `jurisdiction` (string, nullable, required)
  - `riskLevel` (string, required) One of `unscreened`, `clear`, `medium`, `high`.
  - `riskNotes` (string, nullable, required)
  - `baselinePaymentLimit` (number, nullable, required): The business's baseline payment limit for this counterparty.
  - `paymentLimit` (number, nullable, required): The current payment limit, derived from the risk tier.
  - `lastScreenedAt` (string, nullable, required)
  - `performanceScore` (number, nullable, required): No history is different from a zero score and remains null.
  - `performanceInputs` (object, nullable, required)
  - `createdAt` (string, required)
- `page` (object, required): Where this page sits in the collection.
  - `nextCursor` (string, nullable, required): Pass back as `?cursor=` to continue. Null when the end is reached.
  - `hasMore` (boolean, required): Whether another page follows this one.
  - `count` (integer, required): How many items this response carries.

## Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_request` | An invalid `limit` or `cursor`, a filter value outside its allowed values, or a request body that does not validate. The message names the parameter or the field, and lists the accepted values. |
| 401 | `unauthorized` | No key, or a malformed, unknown or revoked one: "A valid API key is required." |
| 403 | `forbidden` | The key's scopes do not cover this route: "This key cannot do that." Or, on a write, the person who created the key can no longer add records: "This key's issuer can no longer add records in this workspace." |
| 500 | `internal` | An unexpected server error. Implementation details are not exposed. |