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.

Include Per-Entity Permissions

Top-level entity list endpoints accept the opt-in includePermissions query parameter. Its default is false, so existing responses are unchanged. When includePermissions=true, the response adds entityPermissions, an object keyed by the universally unique identifier (UUID) of each entity. Each value is the same ResourcePermission returned for that entity by the permissions API.

curl "{base_url}/api/v1/tables?limit=20&includePermissions=true" \
  -H "Authorization: Bearer {access_token}"

{
  "data": [{ "id": "7f4b...", "name": "orders" }],
  "paging": { "total": 1 },
  "entityPermissions": {
    "7f4b...": {
      "resource": "table",
      "permissions": [
        { "operation": "ViewBasic", "access": "allow" },
        { "operation": "EditDescription", "access": "allow" }
      ]
    }
  }
}

Permissions are computed only for entities in the returned page. Use this option when rendering row actions to avoid one permission request per row. Omit it when permissions aren’t needed.

Examples

Basic Pagination

from metadata.ingestion.ometa.ometa_api import OpenMetadata
from metadata.generated.schema.entity.data.table import Table

metadata = OpenMetadata(config)

# Get first page
first_page = metadata.list_entities(
    entity=Table,
    limit=20
)

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

# Get next page using after cursor
if first_page.paging.after:
    next_page = metadata.list_entities(
        entity=Table,
        limit=20,
        after=first_page.paging.after
    )
    for table in next_page.entities:
        print(table.fullyQualifiedName)

import org.openmetadata.sdk.models.ListParams;

// client is an initialized OpenMetadataClient.

// Get first page
var firstPage = client.tables().list(new ListParams().setLimit(20));

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

// Get next page
if (firstPage.getPaging().getAfter() != null) {
    var nextPage = client.tables().list(
        new ListParams().setLimit(20).setAfter(firstPage.getPaging().getAfter()));
    for (var 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.ingestion.ometa.ometa_api import OpenMetadata
from metadata.generated.schema.entity.data.table import Table

metadata = OpenMetadata(config)

# Iterate through all tables
for table in metadata.list_all_entities(entity=Table, limit=100):
    print(table.fullyQualifiedName)
    # Process each table...

import org.openmetadata.sdk.models.ListParams;

// client is an initialized OpenMetadataClient.

String afterCursor = null;

do {
    var params = new ListParams().setLimit(100);
    if (afterCursor != null) {
        params.setAfter(afterCursor);
    }
    var page = client.tables().list(params);

    for (var 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.ingestion.ometa.ometa_api import OpenMetadata
from metadata.generated.schema.entity.data.table import Table

metadata = OpenMetadata(config)

# List tables from a specific database
tables = metadata.list_entities(
    entity=Table,
    params={"database": "prod.analytics"},
    limit=50
)

for table in tables.entities:
    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

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

Collaboration

AI SDK

SDK

Discovery

Lineage

Data Contracts

Teams And Users

Data Governance

Data Quality

Alerts

Incidents

Main Concepts

Pagination

Response Fields

Include Per-Entity Permissions

Examples

Iterating Through All Results

Include Fields

Best Practices

Search API

​Pagination

​Pagination Parameters

​Response Fields

​Include Per-Entity Permissions

​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

Include Per-Entity Permissions

Examples

Basic Pagination

Offset-Based Pagination

Iterating Through All Results

Filtering with Pagination

Include Fields

Best Practices

Pagination vs Search