List data

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. Large responses may return documents through docsUrl instead of inline docs. See Large results for REST download instructions and SDK behavior.

Parameter	Description	Type	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
refKind	Ref type: `branch`, `tag`, or `alias`; use with `refName`.	string
refName	Ref name; use with `refKind`.	string

Treat pageToken as opaque and return it unchanged to the same endpoint. When selecting a ref, supply refKind and refName together; omitting both reads from main. Tokens record a search position, not a snapshot pin. A branch may advance or an alias may be retargeted between pages. For a stable multi-page export, select the same immutable tag on every page and keep filter, partition, field-selection, and vector options unchanged. Restart pagination when the environment, project, collection, ref, or those options change. List requests do not support consistentRead.

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)

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.

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,
  });
}

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
  }
}

# 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}"

# List documents through an alias
curl -X GET "$BASE_URL/projects/$PROJECT_NAME/collections/${collection_name}/docs?refKind=alias&refName=production-read" \
  -H "x-api-key: ${YOUR_API_KEY}"

The response includes total (the number of documents returned in this page, including any delivered through docsUrl), the current page of documents, and an optional token for the next page. total is not the collection size:

{
  "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": "ZXlKcFpDSTZJQ0poWW1NaQ",
  "isDocsInline": true
}

Extended list request

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

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,
    )

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,
});

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
}

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,
    "ref": { "kind": "alias", "name": "production-read" }
  }'

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	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
ref	Branch, tag, or alias selector as `{ "kind": "...", "name": "..." }`.	object	`main` branch

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.

{
  "filter": {
    "bool": [
      {
        "queryString": {
          "query": "category:docs"
        },
        "occur": "filter"
      },
      {
        "queryString": {
          "query": "title:LambdaDB"
        },
        "occur": "must"
      }
    ]
  }
}

When you use nextPageToken with the extended endpoint, keep the same filter, partitionFilter, fields, includeVectors, and ref options across pages.

To fetch specific documents by ID, use the fetch endpoint. To run ranked text, vector, sparse-vector, or hybrid search, use the query API.

Get started

Migrations

Collections

Data versioning

Documents

Search

Manage Costs

Security

Extended list request

​Extended list request

Extended list request