---
title: List Chats
description: Lists chats accessible to the authenticated user. Use metadata[key]=value style query parameters to filter by metadata.
product: Platform API
type: reference
prerequisites:
  - /docs/api/platform/quickstart
---

# List Chats



<EndpointDisplay method="get" path="/chats" versionPrefix="/v2" />

## Usage [#usage]

<CustomCodeBlock languages="['TypeScript', 'cURL']" defaultLanguage="TypeScript">
  <CodeVariant
    language="TypeScript"
    title="TypeScript Example"
    code="`import { v0 } from 'v0-sdk'

const result = await v0.chats.list()

console.log(result)`"
  />

  <CodeVariant
    language="cURL"
    title="cURL Example"
    code="`curl -X GET &#x22;https://api.v0.dev/api/v2/chats&#x22; \
  -H &#x22;Authorization: Bearer $V0_API_KEY&#x22; \
  -H &#x22;Content-Type: application/json&#x22;`"
  />
</CustomCodeBlock>

## API Signature [#api-signature]

### Request [#request]

#### Query Parameters [#query-parameters]

<APISignature
  parameters="[
  {
    &#x22;name&#x22;: &#x22;limit&#x22;,
    &#x22;type&#x22;: &#x22;integer&#x22;,
    &#x22;required&#x22;: false,
    &#x22;description&#x22;: &#x22;Maximum number of chats to return (1-100, default 20).&#x22;,
    &#x22;deprecated&#x22;: false
  },
  {
    &#x22;name&#x22;: &#x22;cursor&#x22;,
    &#x22;type&#x22;: &#x22;string&#x22;,
    &#x22;required&#x22;: false,
    &#x22;description&#x22;: &#x22;Pagination cursor returned from a previous response.&#x22;,
    &#x22;deprecated&#x22;: false
  },
  {
    &#x22;name&#x22;: &#x22;authorId&#x22;,
    &#x22;type&#x22;: &#x22;string&#x22;,
    &#x22;required&#x22;: false,
    &#x22;description&#x22;: &#x22;Restrict results to chats created by this user. Must be a member of the calling scope.&#x22;,
    &#x22;deprecated&#x22;: false
  },
  {
    &#x22;name&#x22;: &#x22;vercelProjectId&#x22;,
    &#x22;type&#x22;: &#x22;string&#x22;,
    &#x22;required&#x22;: false,
    &#x22;description&#x22;: &#x22;Restrict results to chats associated with this Vercel project.&#x22;,
    &#x22;deprecated&#x22;: false
  },
  {
    &#x22;name&#x22;: &#x22;metadata&#x22;,
    &#x22;type&#x22;: &#x22;Record<string, string>&#x22;,
    &#x22;required&#x22;: false,
    &#x22;description&#x22;: &#x22;Filter by metadata, e.g. metadata[environment]=production. Returns chats matching all supplied key-value pairs.&#x22;,
    &#x22;deprecated&#x22;: false
  }
]"
/>

### Response [#response]

<APISignature
  parameters="[
  {
    &#x22;name&#x22;: &#x22;chats&#x22;,
    &#x22;type&#x22;: &#x22;object[]&#x22;,
    &#x22;required&#x22;: true,
    &#x22;description&#x22;: &#x22;The chats in this page.&#x22;,
    &#x22;deprecated&#x22;: false,
    &#x22;arrayItems&#x22;: {
      &#x22;name&#x22;: &#x22;item&#x22;,
      &#x22;type&#x22;: &#x22;object&#x22;,
      &#x22;required&#x22;: true,
      &#x22;description&#x22;: &#x22;&#x22;,
      &#x22;deprecated&#x22;: false,
      &#x22;properties&#x22;: [
        {
          &#x22;name&#x22;: &#x22;id&#x22;,
          &#x22;type&#x22;: &#x22;string&#x22;,
          &#x22;required&#x22;: true,
          &#x22;description&#x22;: &#x22;Unique chat identifier.&#x22;,
          &#x22;deprecated&#x22;: false
        },
        {
          &#x22;name&#x22;: &#x22;title&#x22;,
          &#x22;type&#x22;: &#x22;string&#x22;,
          &#x22;required&#x22;: false,
          &#x22;description&#x22;: &#x22;Chat title, if generated.&#x22;,
          &#x22;deprecated&#x22;: false
        },
        {
          &#x22;name&#x22;: &#x22;privacy&#x22;,
          &#x22;type&#x22;: &#x22;'public' | 'private' | 'team' | 'team-edit' | 'unlisted'&#x22;,
          &#x22;required&#x22;: true,
          &#x22;description&#x22;: &#x22;Visibility setting of the chat.&#x22;,
          &#x22;deprecated&#x22;: false
        },
        {
          &#x22;name&#x22;: &#x22;createdAt&#x22;,
          &#x22;type&#x22;: &#x22;string&#x22;,
          &#x22;required&#x22;: true,
          &#x22;description&#x22;: &#x22;ISO timestamp of when the chat was created.&#x22;,
          &#x22;deprecated&#x22;: false
        },
        {
          &#x22;name&#x22;: &#x22;updatedAt&#x22;,
          &#x22;type&#x22;: &#x22;string&#x22;,
          &#x22;required&#x22;: false,
          &#x22;description&#x22;: &#x22;ISO timestamp of when the chat was last updated.&#x22;,
          &#x22;deprecated&#x22;: false
        },
        {
          &#x22;name&#x22;: &#x22;authorId&#x22;,
          &#x22;type&#x22;: &#x22;string&#x22;,
          &#x22;required&#x22;: true,
          &#x22;description&#x22;: &#x22;ID of the user who created the chat.&#x22;,
          &#x22;deprecated&#x22;: false
        },
        {
          &#x22;name&#x22;: &#x22;vercelProjectId&#x22;,
          &#x22;type&#x22;: &#x22;string&#x22;,
          &#x22;required&#x22;: false,
          &#x22;description&#x22;: &#x22;Associated Vercel project ID, if any.&#x22;,
          &#x22;deprecated&#x22;: false
        },
        {
          &#x22;name&#x22;: &#x22;metadata&#x22;,
          &#x22;type&#x22;: &#x22;Record<string, string>&#x22;,
          &#x22;required&#x22;: true,
          &#x22;description&#x22;: &#x22;User-defined key-value metadata.&#x22;,
          &#x22;deprecated&#x22;: false
        },
        {
          &#x22;name&#x22;: &#x22;writePermission&#x22;,
          &#x22;type&#x22;: &#x22;boolean&#x22;,
          &#x22;required&#x22;: true,
          &#x22;description&#x22;: &#x22;Whether the caller has write access to this chat.&#x22;,
          &#x22;deprecated&#x22;: false
        }
      ]
    }
  },
  {
    &#x22;name&#x22;: &#x22;cursor&#x22;,
    &#x22;type&#x22;: &#x22;string | null&#x22;,
    &#x22;required&#x22;: true,
    &#x22;description&#x22;: &#x22;Cursor to fetch the next page, or null if there are no more chats.&#x22;,
    &#x22;deprecated&#x22;: false
  }
]"
/>