Skip to main content

​
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

ParameterTypeDefaultDescription
limitintegerVaries by endpointPage 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.
beforestring-Cursor for the previous page on cursor-paginated endpoints
afterstring-Cursor for the next page on cursor-paginated endpoints
offsetintegerWhen supportedRow 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:
FieldTypeDescription
totalintegerTotal count of matching resources
beforestringCursor for the previous page (if available)
afterstringCursor 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

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)

​
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...

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

​
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

1

Use reasonable page sizes

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

Follow cursor pages sequentially

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

Keep offset paging stable

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

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.
5

Request only needed fields

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

Implement retry logic

Handle transient errors gracefully when paginating through large datasets.
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