# List a repository's caches

> List the entries actions/cache has saved in a repository (total_count, actions_caches): each with its id (a number), key, ref (the ref whose run saved it; a pull request from outside saves under untrusted:<ref>), version (the hash of its paths; empty for one g1t's own actions/cache saved), size_in_bytes, created_at and last_accessed_at (its last restore or lookup).

<div class="g1t-endpoint"><span class="g1t-method" data-method="get">GET</span><code>/repos/{owner}/{name}/actions/caches</code></div>

Narrow with key (entries whose key starts with it) and ref; order with sort (last_accessed_at, created_at or size_in_bytes; last_accessed_at by default) and direction (asc or desc; desc by default); page with page and per_page (30 by default, at most 100). Needs the Read role.

`key` matches keys that start with it. Entries past their 28 days, or unused for 7, are swept within the hour and are not listed once they are.

- **Authentication:** Required. Send an [access token](/reference/api/#authentication) as `Authorization: Bearer`.
- **MCP tool:** [`workflow`](/reference/mcp/#workflow) with `action` `list_caches`, and the same inputs
- **Scope:** An access token needs [`workflows:read`](/guides/authentication/#scopes).

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | Yes | The workspace that owns the repository. |
| `name` | string | Yes | The repository's name. |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `key` | string | No | Only entries whose key starts with this. |
| `ref` | string | No | A full ref, e.g. refs/heads/main or refs/pull/7/merge. |
| `sort` | string | No | What to order by: last_accessed_at unless you say. One of `last_accessed_at`, `created_at`, `size_in_bytes`. |
| `direction` | string | No | desc unless you say. One of `asc`, `desc`. |
| `page` | integer | No | The page, from 1. |
| `per_page` | integer | No | Entries a page: 30 unless you say, at most 100. |

## Example request

```sh
curl "https://api.g1t.sh/repos/flagon-io/g1t/actions/caches?key=cargo-test-&sort=size_in_bytes&per_page=2" \
  -H "Authorization: Bearer $G1T_TOKEN"
```

## Example response

A successful request answers `200` with:

```json
{
  "total_count": 3,
  "actions_caches": [
    {
      "id": 9184,
      "key": "cargo-test-Linux-rustc-1.99.0-5f1c3a9e7b2d",
      "ref": "refs/heads/main",
      "version": "",
      "size_in_bytes": 1687203840,
      "created_at": "2026-10-12T09:14:02.511Z",
      "last_accessed_at": "2026-10-12T15:40:19.087Z"
    },
    {
      "id": 9102,
      "key": "cargo-test-Linux-rustc-1.99.0-5f1c3a9e7b2d",
      "ref": "refs/pull/412/merge",
      "version": "",
      "size_in_bytes": 702545920,
      "created_at": "2026-10-12T11:02:44.930Z",
      "last_accessed_at": "2026-10-12T11:02:44.930Z"
    }
  ]
}
```

## Errors

A failed request answers with one of these statuses and a body like `{"error": {"code": "not_found", "message": "Repository not found."}}`. See [errors](/reference/api/#errors).

| Status | Code | When |
| --- | --- | --- |
| 401 | `unauthenticated` | A token is required, or the one sent is not valid. |
| 403 | `forbidden` | The token is valid but not allowed to do this, such as a member-only change, or a token without the scope it needs. |
| 404 | `not_found` | It does not exist, or you cannot see it. |
| 422 | `invalid` | The input is not valid. `message` says which field and why. |