> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.videogen.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.videogen.io/_mcp/server.

# List projects

GET https://api.videogen.io/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.

Reference: https://docs.videogen.io/rest-api-reference/projects/list-projects

## Authentication

- `Authorization` header (bearer token, required) — API key from [app.videogen.io/api](https://app.videogen.io/api). The full key is only shown once when you create it.

## Request

### Query parameters

- `limit` (integer, optional, default: 50) — Maximum number of items to return in the page. Defaults to 50; capped at 200. See [Pagination](/pagination).
- `cursor` (string, optional) — Opaque pagination cursor returned as `nextCursor` by the previous page. Omit on the first request. Cursors are tied to the endpoint that produced them and must be passed unmodified. See [Pagination](/pagination).
- `selfOnly` (boolean, optional, default: false) — When true, returns only items created by the API key's owner. When false (default), returns all items accessible to the team.
- `includeUiProjects` (boolean, optional, default: false) — When true, includes dashboard-created projects in addition to API-created projects. When false (default), returns only API-created projects.

## Response

### 200

Paginated list of projects.

- `projects` (list of ProjectResponse, required)
- `hasMore` (boolean, required) — When true, there are more projects available. Pass `nextCursor` as the `cursor` query param to fetch the next page.
- `nextCursor` (string, required, nullable) — Opaque cursor to fetch the next page. `null` when `hasMore` is false.

## Types

### ProjectResponse

Simplified project metadata.

- `projectId` (string, required) — Opaque project id (e.g. `vg_proj_...`).
- `assistantId` (string, required, nullable) — 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.
- `status` (enum, required) — High-level project status.
  - Allowed values: `generating`, `ready`
- `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, 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.

### AspectRatio

Aspect ratio as a width:height pair (e.g. 16 and 9 for 16:9). Not pixel dimensions.

- `width` (integer, required)
- `height` (integer, required)

## Examples

**Response**

```json
{
  "projects": [
    {
      "projectId": "vg_proj_9dTk3mQ1rZ7xP4vN2sB6wc",
      "title": "Staying hydrated",
      "aspectRatio": {
        "width": 16,
        "height": 9
      },
      "status": "ready",
      "createdAt": 1779537600,
      "updatedAt": 1779537870,
      "projectUrl": "https://app.videogen.io/project/1f0a2b3c-4d5e-6789-ab12-cdef34567890"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

**SDK Code**

```typescript
import { VideoGen } from "@videogen/sdk";

const client = new VideoGen({ apiKey: "sk_videogen_live_..." });

await client.projects.listProjects();
```

```python
from videogen import VideoGen

client = VideoGen(api_key="sk_videogen_live_...")

client.projects.list_projects()
```