Pagination

OpenMetadata uses both cursor-based and offset-based pagination, depending on the endpoint. Most top-level entity list endpoints use cursor-based pagination for stable traversal, while many sub-resource and specialized endpoints use limit plus offset.

Pagination Parameters

Parameter	Type	Default	Description
`limit`	integer	Varies by endpoint	Page size. Many top-level entity list endpoints default to `10` and allow up to `1,000,000`, while offset-based sub-resource endpoints often use lower defaults and caps, such as `1,000` for table columns.
`before`	string	-	Cursor for the previous page on cursor-paginated endpoints
`after`	string	-	Cursor for the next page on cursor-paginated endpoints
`offset`	integer	When supported	Row offset on offset-paginated endpoints. If omitted, the endpoint starts from the first page.

Response Fields

The paging object varies by endpoint. Cursor-paginated responses usually include:

Field	Type	Description
`total`	integer	Total count of matching resources
`before`	string	Cursor for the previous page (if available)
`after`	string	Cursor for the next page (if available)

Offset-paginated endpoints also return total, and may include offset, limit, or cursor-style before/after fields depending on the resource. Check the endpoint schema for the exact response shape.

Examples

Basic Pagination

from metadata.sdk import Tables
from metadata.sdk.entities.tables import TableListParams

# Get first page
params = TableListParams.builder().limit(20).build()
first_page = Tables.list(params)

print(f"Total tables: {first_page.paging.total}")
for table in first_page.data:
    print(table.fullyQualifiedName)

# Get next page using after cursor
if first_page.paging.after:
    next_params = TableListParams.builder().limit(20).after(first_page.paging.after).build()
    next_page = Tables.list(next_params)
    for table in next_page.data:
        print(table.fullyQualifiedName)

import org.openmetadata.client.api.TablesApi;
import org.openmetadata.client.model.TableList;

TablesApi tablesApi = client.buildClient(TablesApi.class);

// Get first page
TableList firstPage = tablesApi.listTables(null, 20, null, null, null);

System.out.println("Total tables: " + firstPage.getPaging().getTotal());
for (Table table : firstPage.getData()) {
    System.out.println(table.getFullyQualifiedName());
}

// Get next page
if (firstPage.getPaging().getAfter() != null) {
    TableList nextPage = tablesApi.listTables(
        null, 20, null, firstPage.getPaging().getAfter(), null
    );
    for (Table table : nextPage.getData()) {
        System.out.println(table.getFullyQualifiedName());
    }
}

# Get first page
curl -X GET "https://your-company.open-metadata.org/api/v1/tables?limit=20" \
  -H "Authorization: Bearer $TOKEN"

# Response includes paging.after cursor
# {
#   "data": [...],
#   "paging": {
#     "total": 150,
#     "after": "eyJsYXN0SWQiOiIxMjM0NTY3ODkwIn0="
#   }
# }

# Get next page using after cursor
curl -X GET "https://your-company.open-metadata.org/api/v1/tables?limit=20&after=eyJsYXN0SWQiOiIxMjM0NTY3ODkwIn0=" \
  -H "Authorization: Bearer $TOKEN"

Offset-Based Pagination

Use offset on endpoints that document it, such as /v1/tables/{id}/columns:

# Get first 20 columns
curl "{base_url}/api/v1/tables/{id}/columns?limit=20&offset=0" \
  -H "Authorization: Bearer {access_token}"

# Get next 20 columns
curl "{base_url}/api/v1/tables/{id}/columns?limit=20&offset=20" \
  -H "Authorization: Bearer {access_token}"

Iterating Through All Results

Iterating Results

from metadata.sdk import Tables

# Auto-paginate through all tables
for table in Tables.list().auto_paging_iterable():
    print(table.fullyQualifiedName)
    # Process each table...

import org.openmetadata.client.api.TablesApi;

TablesApi tablesApi = client.buildClient(TablesApi.class);
String afterCursor = null;

do {
    TableList page = tablesApi.listTables(null, 100, null, afterCursor, null);

    for (Table table : page.getData()) {
        System.out.println(table.getFullyQualifiedName());
        // Process each table...
    }

    afterCursor = page.getPaging().getAfter();
} while (afterCursor != null);

#!/bin/bash

after_cursor=""

while true; do
  # Build URL with optional cursor
  url="https://your-company.open-metadata.org/api/v1/tables?limit=100"
  if [ -n "$after_cursor" ]; then
    url="${url}&after=${after_cursor}"
  fi

  # Fetch page
  response=$(curl -s -X GET "$url" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json")

  # Process results
  echo "$response" | jq -r '.data[].fullyQualifiedName'

  # Get next cursor
  after_cursor=$(echo "$response" | jq -r '.paging.after // empty')

  # Exit if no more pages
  if [ -z "$after_cursor" ]; then
    break
  fi
done

Filtering with Pagination

Combine pagination with filters for efficient data retrieval:

Filtering

from metadata.sdk import Tables
from metadata.sdk.entities.tables import TableListParams

# List tables from a specific database with fields
params = TableListParams.builder() \
    .limit(50) \
    .fields(["owners", "tags"]) \
    .build()
tables = Tables.list(params)

for table in tables.data:
    print(table.fullyQualifiedName)

# Filter tables by database
curl -X GET "https://your-company.open-metadata.org/api/v1/tables?database=prod.analytics&limit=50" \
  -H "Authorization: Bearer $TOKEN"

Include Fields

Control which fields are returned in the response using the fields parameter:

# Request specific fields
curl -X GET "https://your-company.open-metadata.org/api/v1/tables?fields=owner,tags,columns&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Common field options for tables:

owner - Include owner information
tags - Include tags and classifications
columns - Include column definitions
followers - Include followers
tableConstraints - Include constraints
usageSummary - Include usage statistics

Best Practices

Use reasonable page sizes

Start with limit=50-100. Larger pages reduce API calls but increase memory usage.

Follow cursor pages sequentially

On cursor-paginated endpoints, always use the returned before and after cursors. Don’t try to construct cursor values manually.

Keep offset paging stable

On offset-paginated endpoints, keep filters and sort order fixed while incrementing offset predictably from one page to the next.

Handle empty results

Use the endpoint’s pagination signal to detect the end of results, such as a missing after cursor or an empty page.

Request only needed fields

Use the fields parameter to reduce response size and improve performance.

Implement retry logic

Handle transient errors gracefully when paginating through large datasets.

Pagination vs Search

For finding specific resources, consider using the Search API instead of paginating through all results:

# Search is faster for finding specific resources
curl -X GET "https://your-company.open-metadata.org/api/v1/search/query?q=customers&index=table_search_index" \
  -H "Authorization: Bearer $TOKEN"

Search API

Learn about searching and filtering metadata

API Reference

Data Assets

AI SDK

SDK

Discovery

Lineage

Data Contracts

Teams And Users

Data Governance

Data Quality

Main Concepts

Pagination

Response Fields

Examples

Iterating Through All Results

Include Fields

Best Practices

Search API

​Pagination

​Pagination Parameters

​Response Fields

​Examples

​Basic Pagination

​Offset-Based Pagination

​Iterating Through All Results

​Filtering with Pagination

​Include Fields

​Best Practices

​Pagination vs Search

Search API

Pagination

Pagination Parameters

Response Fields

Examples

Basic Pagination

Offset-Based Pagination

Iterating Through All Results

Filtering with Pagination

Include Fields

Best Practices

Pagination vs Search