> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lambdadb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List data

> Paginate through documents in a LambdaDB collection using the list endpoint. Useful for scanning, exporting, filtering, or iterating over stored records.

This page shows you how to use the list endpoint to list documents in a collection. Use this when you need to iterate over documents (for example, to export or scan) without running a ranked search.

| Parameter      | Description                                                   | Type    | Required | Default |
| :------------- | :------------------------------------------------------------ | :------ | :------- | :------ |
| size           | Max number of documents to return per page (1–100).           | integer |          | 100     |
| pageToken      | Token for the next page of results.                           | string  |          |         |
| includeVectors | Indicates whether vector values are included in the response. | boolean |          | false   |

<CodeGroup>
  ```python Python theme={null}
  from lambdadb import LambdaDB

  with LambdaDB(
      project_api_key="YOUR_API_KEY",
      base_url="YOUR_BASE_URL",
      project_name="YOUR_PROJECT_NAME",
  ) as client:
      coll = client.collection("my_collection")
      # List first page of documents
      res = coll.docs.list(size=10)
      # `res.docs` contains items (each item includes `doc` and metadata).
      # `res.documents` contains document bodies only.
      for item in res.docs:
          print(item)

      # List next page using the token from the previous response
      if res.next_page_token:
          res_next = coll.docs.list(size=10, page_token=res.next_page_token)
  ```

  <Note>
    Python: `LambdaDB` supports context manager usage. `__enter__` returns the client, and `__exit__` calls `client.close()` (closing the SDK-owned HTTP client) and makes the client unusable after the `with` block. If you don't use `with`, call `client.close()` when you're done. If you pass a custom `client=`/`async_client=`, you own closing it.
  </Note>

  ```typescript TypeScript theme={null}
  import { LambdaDBClient } from "@functional-systems/lambdadb";

  const client = new LambdaDBClient({
    projectApiKey: "YOUR_API_KEY",
    baseUrl: "YOUR_BASE_URL",
    projectName: "YOUR_PROJECT_NAME",
  });
  const collection = client.collection("my_collection");

  // List first page
  const res = await collection.docs.list({ size: 20 });
  console.log(res.docs?.length, res.total);

  // List next page
  if (res.nextPageToken) {
    const resNext = await collection.docs.list({
      size: 20,
      pageToken: res.nextPageToken,
    });
  }
  ```

  ```go Go theme={null}
  package main

  import (
    "context"
    "log"
    lambdadb "github.com/lambdadb/go-lambdadb"
  )

  func main() {
    ctx := context.Background()
    client := lambdadb.New(
      lambdadb.WithBaseURL("YOUR_BASE_URL"),
      lambdadb.WithProjectName("YOUR_PROJECT_NAME"),
      lambdadb.WithAPIKey("YOUR_API_KEY"),
    )
    coll := client.Collection("my_collection")

    // List first page
    res, err := coll.Docs().List(ctx, &lambdadb.ListDocsOpts{Size: lambdadb.Int64(10)})
    if err != nil {
      log.Fatal(err)
    }
    for _, d := range res.Docs {
      _ = d
    }

    // List next page
    if res.NextPageToken != nil {
      resNext, _ := coll.Docs().List(ctx, &lambdadb.ListDocsOpts{
        Size:      lambdadb.Int64(10),
        PageToken: res.NextPageToken,
      })
      _ = resNext
    }
  }
  ```

  ```bash cURL theme={null}
  # List first page ($BASE_URL and $PROJECT_NAME match SDK base_url / project_name)
  curl -X GET "$BASE_URL/projects/$PROJECT_NAME/collections/${collection_name}/docs?size=10" \
    -H "x-api-key: ${YOUR_API_KEY}"

  # Include vector values when needed
  curl -X GET "$BASE_URL/projects/$PROJECT_NAME/collections/${collection_name}/docs?size=10&includeVectors=true" \
    -H "x-api-key: ${YOUR_API_KEY}"

  # List next page (use nextPageToken from previous response)
  curl -X GET "$BASE_URL/projects/$PROJECT_NAME/collections/${collection_name}/docs?size=10&pageToken=YOUR_PAGE_TOKEN" \
    -H "x-api-key: ${YOUR_API_KEY}"
  ```
</CodeGroup>

The response includes the total count, the current page of documents, and an optional token for the next page:

```json theme={null}
{
  "total": 2,
  "docs": [
    {
      "collection": "example-collection-name",
      "doc": {
        "id": "doc-1",
        "title": "Example document 1",
        "category": "docs"
      }
    },
    {
      "collection": "example-collection-name",
      "doc": {
        "id": "doc-2",
        "title": "Example document 2",
        "category": "docs"
      }
    }
  ],
  "nextPageToken": "eyJpZCI6ICJhYmMiLCAiY3JlYXRlZF9hdCI6ICIyMDI0LTExLTA1VDE0OjI3OjU2KzAwOjAwIn0=",
  "isDocsInline": true
}
```

## Extended list request

For filtering, partition filtering, field selection, or a JSON request body, use the extended list endpoint:

<CodeGroup>
  ```python Python theme={null}
  from lambdadb import LambdaDB

  with LambdaDB(
      project_api_key="YOUR_API_KEY",
      base_url="YOUR_BASE_URL",
      project_name="YOUR_PROJECT_NAME",
  ) as client:
      coll = client.collection("my_collection")

      res = coll.docs.list(
          size=10,
          filter_={"queryString": {"query": "category:docs"}},
          partition_filter={"field": "tenant", "in": ["acme"]},
          fields={"include": ["id", "title", "category"]},
          include_vectors=False,
      )
  ```

  ```typescript TypeScript theme={null}
  import { LambdaDBClient } from "@functional-systems/lambdadb";

  const client = new LambdaDBClient({
    projectApiKey: "YOUR_API_KEY",
    baseUrl: "YOUR_BASE_URL",
    projectName: "YOUR_PROJECT_NAME",
  });

  const res = await client.collection("my_collection").docs.list({
    size: 10,
    filter: { queryString: { query: "category:docs" } },
    partitionFilter: { field: "tenant", in: ["acme"] },
    fields: { include: ["id", "title", "category"] },
    includeVectors: false,
  });
  ```

  ```go Go theme={null}
  package main

  import (
    "context"
    "log"

    lambdadb "github.com/lambdadb/go-lambdadb"
    "github.com/lambdadb/go-lambdadb/models/components"
  )

  func main() {
    ctx := context.Background()
    client := lambdadb.New(
      lambdadb.WithBaseURL("YOUR_BASE_URL"),
      lambdadb.WithProjectName("YOUR_PROJECT_NAME"),
      lambdadb.WithAPIKey("YOUR_API_KEY"),
    )

    fields := components.CreateFieldsSelectorUnionFieldsSelector1(components.FieldsSelector1{
      Include: []string{"id", "title", "category"},
    })

    res, err := client.Collection("my_collection").Docs().List(ctx, &lambdadb.ListDocsOpts{
      Size: lambdadb.Int64(10),
      Filter: map[string]any{
        "queryString": map[string]any{"query": "category:docs"},
      },
      PartitionFilter: &components.PartitionFilter{
        Field: "tenant",
        In:    []string{"acme"},
      },
      Fields:         &fields,
      IncludeVectors: lambdadb.Bool(false),
    })
    if err != nil {
      log.Fatal(err)
    }
    _ = res
  }
  ```

  ```bash cURL theme={null}
  curl -X POST "$BASE_URL/projects/$PROJECT_NAME/collections/${collection_name}/docs/list" \
    -H "Content-Type: application/json" \
    -H "x-api-key: ${YOUR_API_KEY}" \
    --data '{
      "size": 10,
      "filter": {
        "queryString": {
          "query": "category:docs"
        }
      },
      "partitionFilter": {
        "field": "tenant",
        "in": ["acme"]
      },
      "fields": {
        "include": ["id", "title", "category"]
      },
      "includeVectors": false
    }'
  ```
</CodeGroup>

The SDK scoped list helpers (`docs.list` in Python and TypeScript, `Docs().List` in Go) use the extended list request automatically when you pass filter, partition filter, or field-selection options.
In Go, pass these as `Filter`, `PartitionFilter`, `Fields`, and `IncludeVectors` on `lambdadb.ListDocsOpts`.

The extended list request body supports:

| Parameter       | Description                                                                         | Type    | Required | Default |
| :-------------- | :---------------------------------------------------------------------------------- | :------ | :------- | :------ |
| size            | Max number of documents to return per page (1–100).                                 | integer |          | 100     |
| pageToken       | Token for the next page of results.                                                 | string  |          |         |
| filter          | Filter applied before pagination. Supports `queryString` and nested `bool` filters. | object  |          |         |
| partitionFilter | Restricts the request to matching partition values.                                 | object  |          |         |
| fields          | Field selector with `include` and/or `exclude`. Use dot notation for nested fields. | object  |          |         |
| includeVectors  | Indicates whether vector values are included in the response.                       | boolean |          | false   |

`filter` uses the same `queryString` and `bool` shapes as the query API. List filters do not run vector or ranking queries.
Use `partitionFilter` only for collections configured with a partition field.
Inside a `bool` filter, `occur` can be `filter`, `must`, `must_not`, or `should`; when omitted, it defaults to `should`.

```json theme={null}
{
  "filter": {
    "bool": [
      {
        "queryString": {
          "query": "category:docs"
        },
        "occur": "filter"
      },
      {
        "queryString": {
          "query": "title:LambdaDB"
        },
        "occur": "must"
      }
    ]
  }
}
```

<Note>
  When you use `nextPageToken` with the extended endpoint, keep the same `filter`, `partitionFilter`, `fields`, and `includeVectors` options across pages.
</Note>

<Note>
  To fetch specific documents by ID, use the [fetch](/guides/documents/fetch-data) endpoint. To run ranked text, vector, sparse-vector, or hybrid search, use the [query](/guides/search/search-overview) API.
</Note>