---
title: "List apps"
method: POST
path: "/v2/apps.listApps"
tags: ["apps"]
---

# List apps

`POST /v2/apps.listApps`

Retrieve a paginated list of apps within a project.

Use this to enumerate every app in a project. Results are ordered by app id and paginated; when `hasMore` is true, pass the returned `cursor` to fetch the next page.

**Required Permissions**

Your root key must have the following permission:
- `app.*.read_app` (to read apps in any project)

## Request body

- V2AppsListAppsRequestBody
  - `project` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - `limit` integer — Maximum number of apps to return per request. Balance between response size and number of pagination calls needed.
  - `cursor` string — Pagination cursor from a previous response to fetch the next page. Use when `hasMore: true` in the previous response.
  - `search` string — Free-form text to filter apps. Returns apps whose ID, name, or slug contains the search string. Matching is case-insensitive.

## Response `200`

Successfully retrieved a paginated list of apps. Use the pagination cursor for additional results when `hasMore: true`.

- V2AppsListAppsResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` App[], required — Array of apps in the project, ordered by app id.
    - `id` string, required — The unique identifier of the app, generated by Unkey.
    - `name` string, required — Human-readable name for this app.
    - `slug` string, required — URL-safe handle for this app, unique within its project. Chosen at creation time.
    - `git` AppGit
      - `repository` string, required — The connected GitHub repository, as "owner/repo".
      - `defaultBranch` string — The branch this app's deployments track.
    - `currentDeploymentId` string — The identifier of the deployment currently serving this app. Omitted if the app has no active deployment yet.
    - `isRolledBack` boolean, required — Whether the app is currently serving a rolled-back deployment rather than its latest one.
    - `deleteProtection` boolean, required — Whether delete protection is enabled for this app. When true, the app cannot be deleted until protection is disabled.
    - `createdAt` integer, required — Unix timestamp in milliseconds when the app was created.
    - `updatedAt` integer — Unix timestamp in milliseconds when the app was last updated. Omitted if the app has never been updated.
  - `pagination` Pagination, required — Pagination metadata for list endpoints. Provides information necessary to traverse through large result sets efficiently using cursor-based pagination.
    - `cursor` string — Opaque pagination token for retrieving the next page of results. Include this exact value in the cursor field of subsequent requests. Cursors are temporary and may expire after extended periods.
    - `hasMore` boolean, required — Indicates whether additional results exist beyond this page. When true, use the cursor to fetch the next page. When false, you have reached the end of the result set.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden - Insufficient permissions (requires `app.*.read_app`)
- `404` — Not Found - The requested project does not exist in your workspace
- `429` — Too Many Requests
- `500` — Internal server error

## Changes

- **2026-08-03** `2dcddab7f374` — 1 breaking, 1 info
  - removed the required property `data/items/defaultBranch` from the response with the `200` status
  - added the optional property `data/items/git` to the response with the `200` status
- **2026-07-14** `43ad1ce9a152` — 2 info
  - the endpoint scheme security `bearer` was added to the API
  - the endpoint scheme security `rootKey` was removed from the API
- **2026-07-10** `db25ebfde9a6` — 1 info
  - the response property `pagination` became required for the status `200`
- **2026-07-10** `0b9c06bab707` — 1 info
  - added the new optional request property `search`
- **2026-07-06** `0f7e331eeffa` — 1 breaking
  - removed the required property `data/items/projectId` from the response with the `200` status

[Full history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/apps.listApps/post.md)

---

[API](https://skmtc.dev/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.dev/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/revisions/982b36cad359/schema)