---
title: "List projects"
method: GET
path: "/v1/projects"
tags: ["Projects"]
---

# List projects

`GET /v1/projects`

Returns projects, most recently updated first. By default only API-created projects are included; pass `includeUiProjects=true` to also include dashboard-created projects. Use `selfOnly=true` to restrict results to the calling API key's user; otherwise all matching projects for the team are returned. Cursor-paginated; see the [Pagination](/pagination) guide.

## Query parameters

- `limit` integer
- `cursor` string
- `selfOnly` boolean
- `includeUiProjects` boolean

## Response `200`

Paginated list of projects.

- ListProjectsResponse — Paginated list of projects, most recently updated first. By default only API-created projects are included; pass `includeUiProjects=true` on the request to also include dashboard-created projects.
  - `projects` ProjectResponse[], required
    - `projectId` string, required — Opaque project id (e.g. `vg_proj_...`).
    - `assistantId` string, nullable, required — Opaque id of this project's assistant conversation (e.g. `vg_asst_...`). Use with the Assistant API to send follow-up messages or list the assistant's prior messages for this project. `null` for older projects created before assistant chats were attached at creation time.
    - `title` string, required
    - `aspectRatio` AspectRatio, required — Aspect ratio as a width:height pair (e.g. 16 and 9 for 16:9). Not pixel dimensions.
      - `width` integer, required
      - `height` integer, required
    - `status` 'generating' | 'ready', required — High-level project status.
    - `createdAt` integer, required — Seconds since epoch (Unix timestamp) when the project was created.
    - `updatedAt` integer, required — Seconds since epoch (Unix timestamp) when the project was last updated.
    - `projectUrl` string, uri, required — Deep link to open this project in the VideoGen web editor. Not required for an API-only integration: store `projectId` and use the Projects API (export, remix, metadata). Use `projectUrl` when a person should open the project in the app to review or edit it manually. The project is visible only to members of your team and any project collaborators, the same access model as a project created in the dashboard.
  - `hasMore` boolean, required — When true, there are more projects available. Pass `nextCursor` as the `cursor` query param to fetch the next page.
  - `nextCursor` string, nullable, required — Opaque cursor to fetch the next page. `null` when `hasMore` is false.

## Other responses

- `default` — Error

---

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