# List deployments

> List a repository's deployments wherever they run, newest first: those reported through this API, those g1t Actions made for jobs with an environment:, and g1t.page builds (production and previews).

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

Each has its environment, ref and sha, task, description, payload, transient_environment and production_environment, its latest state (queued, in_progress, success, failure, error or inactive), environment_url and log_url, creator, and source (api, actions or g1t_page), with run_id and run_url for g1t Actions and project and number for g1t.page. Filter by environment, ref, sha (or a prefix), task, state, source and creator; page with page and per_page (30 by default, at most 100). total_count counts every match. Needs the Read role; a public repository's are open to anyone.

Every deployment of the repository in one list, wherever it ran: `source` is `api` for those reported with [`POST /repos/{owner}/{name}/deployments`](/reference/api/deployments/create-deployment/), `actions` for those a g1t Actions job with an `environment:` made, and `g1t_page` for [g1t.page](/guides/deployments/) builds, whose ids start `dpl_`. `state` is the latest status's. See [Deployments API](/guides/deployments-api/).

- **Authentication:** Optional. Public data can be read without a token; send one to see what is private.
- **MCP tool:** [`workflow`](/reference/mcp/#workflow) with `action` `list_deployments`, and the same inputs
- **Scope:** An access token needs [`deployments: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 |
| --- | --- | --- | --- |
| `environment` | string | No | Only this environment's, matched without regard to case. |
| `ref` | string | No | Only deployments of this branch, tag or commit as it was given. |
| `sha` | string | No | Only deployments of this commit, or of commits starting with it. |
| `task` | string | No | Only this task's, such as deploy. |
| `state` | string | No | Only deployments whose latest status has this state. One of `queued`, `in_progress`, `success`, `failure`, `error`, `inactive`. |
| `source` | string | No | Only those reported through the API, made by g1t Actions, or built on g1t.page. One of `api`, `actions`, `g1t_page`. |
| `creator` | string | No | Only those this username (or g1t) made. |
| `page` | integer | No | Which page, from 1. |
| `per_page` | integer | No | How many a page holds, 1 to 100; 30 by default. |

## Example request

```sh
curl "https://api.g1t.sh/repos/flagon-io/g1t/deployments?environment=production&per_page=2" \
  -H "Authorization: Bearer $G1T_TOKEN"
```

## Example response

A successful request answers `200` with:

```json
{
  "deployments": [
    {
      "id": "dep_01kq8m3t5v7x9z1b3d5f7h9k2m",
      "environment": "production",
      "ref": "main",
      "sha": "7c1e9a4b2d6f80135ac9e2b7d4f6a8c0e1b3d5f7",
      "task": "deploy",
      "description": "Deploy",
      "payload": {},
      "transient_environment": false,
      "production_environment": true,
      "state": "success",
      "environment_url": "https://g1t.sh",
      "log_url": "https://g1t.sh/flagon-io/g1t/actions/runs/run_01kq8m2r4t6v8x0z2b4d6f8h0k",
      "creator": "syntaqx",
      "source": "actions",
      "run_id": "run_01kq8m2r4t6v8x0z2b4d6f8h0k",
      "run_url": "https://g1t.sh/flagon-io/g1t/actions/runs/run_01kq8m2r4t6v8x0z2b4d6f8h0k",
      "project": null,
      "number": null,
      "created_at": "2026-10-07T18:02:11.204Z",
      "updated_at": "2026-10-07T18:19:47.881Z"
    }
  ],
  "total_count": 304,
  "page": 1,
  "per_page": 2
}
```

## 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 an agent token outside its repository. |
| 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. |