> For the complete documentation index, see [llms.txt](https://docs.trustlesswork.com/trustless-work/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trustlesswork.com/trustless-work/v2-en/api-rest/escrows/list-escrows.md).

# List Escrows

### **Headers**

<table><thead><tr><th width="366">Name</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td><code>application/json</code></td></tr><tr><td>x-api-key</td><td><code>&#x3C;token></code></td></tr></tbody></table>

### Open API

## GET /escrows

The main listing endpoint. Returns escrows the caller can see, filtered and keyset-paginated.

### Scope

| Value            | Returns                                                                                |
| ---------------- | -------------------------------------------------------------------------------------- |
| `mine` (default) | Escrows your verified wallets participate in, plus escrows attributed to your platform |
| `all`            | Every escrow on the network                                                            |

### Filters

All filters are AND-combined.

| Name                         | Type      | Description                                              |
| ---------------------------- | --------- | -------------------------------------------------------- |
| status                       | string    | Lifecycle status (exact match)                           |
| contractType                 | string    | Contract flavor (exact match)                            |
| engagementId                 | string    | Your own correlation id (exact match)                    |
| contractIds                  | string\[] | Only these addresses. Repeat the param                   |
| participant                  | string    | Wallet (`G…`) that is an on-chain participant            |
| role                         | string    | Combined with `participant`: "wallet X acting as role Y" |
| platformId                   | string    | Escrows attributed to this platform (**tenant-scoped**)  |
| subjectId                    | string    | Escrows attributed to this subject (**tenant-scoped**)   |
| createdAfter / createdBefore | ISO 8601  | Creation window                                          |
| includeSnapshot              | boolean   | `false` drops the heavy `snapshot` field                 |

### Pagination

| Name   | Type                       | Description                           |
| ------ | -------------------------- | ------------------------------------- |
| limit  | number                     | 1–200, default 50                     |
| cursor | string                     | From the previous page's `nextCursor` |
| sort   | `createdAt` \| `updatedAt` | Default `updatedAt`                   |
| order  | `asc` \| `desc`            | Default `desc`                        |

### **What this Endpoint returns?**

Always the paginated envelope — **never a bare array**:

```json
{ "data": [ /* escrow summaries */ ], "hasMore": true, "nextCursor": "eyJ..." }
```

Keep `sort` and `order` identical across pages, or the cursor is rejected with `INVALID_CURSOR`.

### Use Example:

```typescript
import axios from "axios";

const http = axios.create({
  baseURL: "https://beta.api.trustlesswork.com",
  timeout: 10000,
  headers: {
    "Content-Type": "application/json",
    "x-api-key": your_api_key,
  },
});

export const useExample = async () => {
  const params = new URLSearchParams({
    scope: "mine",
    limit: "20",
    sort: "updatedAt",
    order: "desc",
  });

  const { data } = await http.get(`/escrows?${params.toString()}`);
  return data; // { data, hasMore, nextCursor }
}
```

### Paging through everything

```typescript
export const listAll = async () => {
  const all = [];
  let cursor = null;

  do {
    const params = new URLSearchParams({ limit: "100" });
    if (cursor) params.append("cursor", cursor);

    const { data } = await http.get(`/escrows?${params.toString()}`);
    all.push(...data.data);
    cursor = data.hasMore ? data.nextCursor : null;
  } while (cursor);

  return all;
}
```

{% hint style="warning" %}
Filtering by a `platformId` or `subjectId` you do not own returns `403 ESCROW_FILTER_FORBIDDEN`. Filtering by `participant` has no such restriction — on-chain participation is public.
{% endhint %}

{% hint style="info" %}
These reads come from the read-model, which is eventually consistent. Right after submitting a transaction a `404` usually means "not projected yet", not "does not exist" — poll briefly instead of treating it as an error.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.trustlesswork.com/trustless-work/v2-en/api-rest/escrows/list-escrows.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.