# GET /v1/projects (/docs/api/reference/projects/list-projects)



<Endpoint method="GET" path="/v1/projects" auth="Bearer" scope="projects:read" phase="1" />

Returns the organization's projects in reverse-creation order. One project per end-customer is the recommended model — the partner-supplied `customerExternalId` is your handle for looking a project up without having to store Layers IDs on your side.

Filter by status, free-text `search` over project name, or `customerExternalId`. The list is cursor-paginated; pass the `nextCursor` from the previous response to page forward.

<Parameters
  title="Query"
  rows="[
  { name: 'cursor', type: 'string', description: 'Opaque pagination token from a previous response\'s nextCursor.' },
  { name: 'limit', type: 'integer', description: 'Page size, 1–200.', default: '25' },
  { name: 'status', type: 'string', description: 'Filter by project status.', enum: ['active', 'archived'] },
  { name: 'search', type: 'string', description: 'Case-insensitive substring match on project name.' },
  { name: 'customerExternalId', type: 'string', description: 'Return the single project bound to this partner-supplied customer ID.' },
]"
/>

## Example request [#example-request]

<Tabs items="['curl', 'TypeScript', 'Python']">
  <Tab value="curl">
    ```bash
    curl "https://api.layers.com/v1/projects?limit=25&status=active" \
      -H "Authorization: Bearer lp_live_01HX9Y6K7EJ4T2_4QZpN..."
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    const { items, nextCursor } = await layers.projects.list({
      limit: 25,
      status: "active",
    });
    ```
  </Tab>

  <Tab value="Python">
    ```python
    result = layers.projects.list(limit=25, status="active")
    ```
  </Tab>
</Tabs>

## Response [#response]

<Response status="200" description="OK">
  ```json
  {
    "items": [
      {
        "id": "prj_01HX9Y7K8M2P4RSTUV56789AB",
        "name": "Acme Coffee iOS",
        "status": "active",
        "customerExternalId": "acme-coffee",
        "timezone": "America/Los_Angeles",
        "primaryLanguage": "en",
        "ownerEmail": "growth@gicgrowth.com",
        "createdAt": "2026-04-10T09:14:22Z",
        "updatedAt": "2026-04-15T17:01:09Z"
      }
    ],
    "nextCursor": "eyJvZmZzZXQiOjI1fQ=="
  }
  ```
</Response>

## Errors [#errors]

| Status | Code              | When                                        |
| ------ | ----------------- | ------------------------------------------- |
| 422    | `VALIDATION`      | `limit` out of range or `cursor` malformed. |
| 401    | `UNAUTHENTICATED` | Missing or invalid key.                     |
| 403    | `FORBIDDEN_SCOPE` | Key lacks `projects:read`.                  |
| 429    | `RATE_LIMITED`    | Honor `Retry-After`.                        |

## See also [#see-also]

* [`POST /v1/projects`](/docs/api/reference/projects/create-project) — create
* [`GET /v1/projects/:id`](/docs/api/reference/projects/get-project) — read one
* [Projects concept](/docs/api/concepts/projects) — one project per end-customer