---
title: Find Chats
description: Retrieves a list of existing chats, with support for pagination and filtering by favorite status, Vercel project, or Git branch. Helps manage and navigate chat history.
docs_index: /docs/llms.txt
lastUpdated: 2026-10-23
product: v0 API
type: reference
prerequisites:
  - /docs/api/v1/quickstart
---

> For an index of all documentation, see [/docs/llms.txt](/docs/llms.txt).

Retrieves a list of existing chats, with support for pagination and filtering by favorite status, Vercel project, or Git branch. Helps manage and navigate chat history.

#### `GET /v1/chats`

## Usage

```typescript
import { v0 } from 'v0-sdk'

const result = await v0.chats.find({
  limit: '10',
  offset: '0',
  isFavorite: 'false',
  vercelProjectId: 'prj_xxxxx',
  branch: 'main',
})

console.log(result)
```

```bash
curl -X GET "https://api.v0.dev/v1/chats?limit=10&offset=0&isFavorite=false&vercelProjectId=prj_xxxxx&branch=main"   -H "Authorization: Bearer $V0_API_KEY"   -H "Content-Type: application/json"
```

## API Signature

### Request

#### Query Parameters

- `limit?: number` Specifies the maximum number of chat records to return in a single response. Useful for paginating results when there are many chats.
- `offset?: number` Determines the starting point for pagination. Used in conjunction with limit to retrieve a specific page of chat results.
- `isFavorite?: 'true' | 'false'` Filters chats by their "favorite" status. Accepts `"true"` or `"false"` (as strings, not booleans).

  - `"true"`: returns only chats marked as favorites.
  - `"false"`: returns only non-favorite chats.
- `vercelProjectId?: string` Filters chats by the linked Vercel project ID. Only returns chats associated with the specified Vercel project.
- `branch?: string` Filters chats by the Git branch name. Only returns chats that have an active Git connection with the specified branch as the head.

### Response

- `object: 'list'`
- `data: object[]`
  - `item: object`
    - `id?: string` A unique identifier for the chat.
    - `object?: 'chat'` Fixed value identifying this object as a chat.
    - `shareable?: boolean` **Deprecated.** Deprecated: Use the `privacy` field instead. A chat is shareable when privacy is public or unlisted.
    - `privacy?: 'public' | 'private' | 'team' | 'team-edit' | 'unlisted'` Defines the visibility of the chat—private, team-only, or public.
    - `name?: string` An optional name assigned to the chat by the user.
    - `title?: string` **Deprecated.** Deprecated title field preserved for backward compatibility.
    - `createdAt?: string` The ISO timestamp representing when the chat was created.
    - `updatedAt?: string` The ISO timestamp of the last update to the chat.
    - `favorite?: boolean` Indicates whether the chat is marked as a favorite.
    - `authorId?: string` The ID of the user who created the chat.
    - `projectId?: string` **Deprecated.** Optional ID of the v0 project associated with this chat.
    - `vercelProjectId?: string` Optional ID of the linked Vercel project, if connected.
    - `webUrl?: string` Web URL to view this chat in the browser.
    - `apiUrl?: string` API URL to access this chat via the API.
    - `latestVersion?: object` The most recent generated version of the chat, if available.
      - `id: string` A unique identifier for the version.
      - `object: 'version'` Fixed value identifying this object as a version.
      - `status: 'pending' | 'completed' | 'failed'` The current status of the version generation process.
      - `demoUrl?: string` Optional URL for previewing the generated output.
      - `screenshotUrl?: string` An authenticated URL to retrieve a screenshot of this version. Fetching this URL requires the same Authorization: Bearer header as all other API calls — it cannot be used directly as an `<img>` `src`. To display it in a browser, proxy the request server-side and forward the Authorization header. Append `?ignoreCache=1` to bypass the one-week screenshot cache.
      - `createdAt: string` The date and time when the version was created, in ISO 8601 format.
      - `updatedAt?: string` The date and time when the version was last updated, in ISO 8601 format.

---

For a semantic overview of all documentation, see [/docs/sitemap.md](/docs/sitemap.md)

For an index of all available documentation, see [/docs/llms.txt](/docs/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/docs/agents.md](/docs/agents.md)