Pagination

The SDK uses cursor-based pagination for list operations. This page covers how to work with paginated results effectively.

Basic Pagination

All list() methods return a paginated response:

Python
TypeScript

from credoai import CredoAI

client = CredoAI()

# Get the first page
response = client.use_cases.list(page_limit=10)

print(f"Items: {len(response.items)}")
print(f"Has more: {response.pagination.has_more}")
print(f"Next cursor: {response.pagination.next_cursor}")

import { createCredoAIClient } from '@credo-ai/sdk';

const client = createCredoAIClient('your-tenant');

// Get the first page
const { data, error } = await client.useCases.list({ pageLimit: 10 });

if (!error) {
  console.log('Items:', data.items.length);
  console.log('Has more:', data.pagination.hasMore);
  console.log('Next cursor:', data.pagination.nextCursor);
}

Pagination Parameters

Python
TypeScript

Parameter	Type	Description
`page_limit`	int	Number of items per page (default: 50, max: 100)
`page_after`	str	Cursor for the next page (from `pagination.next_cursor`)

Parameter	Type	Description
`pageLimit`	number	Number of items per page (default: 50, max: 100)
`pageAfter`	string	Cursor for the next page (from `pagination.nextCursor`)

Manual Pagination

Iterate through pages manually using the cursor:

Python
TypeScript

all_use_cases = []
cursor = None

while True:
    response = client.use_cases.list(
        page_limit=50,
        page_after=cursor
    )

    all_use_cases.extend(response.items)

    if not response.pagination.has_more:
        break

    cursor = response.pagination.next_cursor

print(f"Total use cases: {len(all_use_cases)}")

const allUseCases = [];
let cursor: string | undefined;

while (true) {
  const { data, error } = await client.useCases.list({
    pageLimit: 50,
    pageAfter: cursor,
  });

  if (error) throw error;

  allUseCases.push(...data.items);

  if (!data.pagination.hasMore) break;
  cursor = data.pagination.nextCursor ?? undefined;
}

console.log('Total use cases:', allUseCases.length);

Automatic Pagination

Python
TypeScript

The list_all() method handles pagination automatically and returns a generator:

# Iterate through all items
for use_case in client.use_cases.list_all(page_size=50):
    print(f"  - {use_case.name}")

Collecting All Items

# Collect all items into a list
all_use_cases = list(client.use_cases.list_all(page_size=50))
print(f"Total: {len(all_use_cases)}")

Memory-Efficient Processing

Using list_all() as a generator is memory-efficient for large datasets:

# Process items one at a time without loading all into memory
for use_case in client.use_cases.list_all(page_size=100):
    process_use_case(use_case)

The TypeScript SDK does not include a built-in listAll() helper. Use a helper function for automatic pagination:

async function listAll<T>(
  fetchPage: (cursor?: string) => Promise<{ data: { items: T[]; pagination: { hasMore?: boolean; nextCursor?: string | null } } | null; error: unknown }>,
): Promise<T[]> {
  const results: T[] = [];
  let cursor: string | undefined;

  while (true) {
    const { data, error } = await fetchPage(cursor);
    if (error || !data) throw error;
    results.push(...data.items);
    if (!data.pagination.hasMore) break;
    cursor = data.pagination.nextCursor ?? undefined;
  }

  return results;
}

// Usage
const allUseCases = await listAll((cursor) =>
  client.useCases.list({ pageLimit: 50, pageAfter: cursor })
);
console.log('Total:', allUseCases.length);

Async Pagination

Python
TypeScript

import asyncio
from credoai import AsyncCredoAI

async def main():
    async with AsyncCredoAI() as client:
        # Async iteration
        async for use_case in client.use_cases.list_all(page_size=50):
            print(f"  - {use_case.name}")

        # Or collect all
        all_cases = [uc async for uc in client.use_cases.list_all()]
        print(f"Total: {len(all_cases)}")

asyncio.run(main())

// TypeScript is async by default — use the same pagination pattern
const { data, error } = await client.useCases.list({ pageLimit: 50 });

if (!error) {
  for (const uc of data.items) {
    console.log(`  - ${uc.name}`);
  }
}

Pagination for Relationships

Python
TypeScript

# List all models for a use case
for model in client.use_case_models.list_all(use_case_id="uc_abc123"):
    print(f"  - {model.name}")

# List all vendors for a model
for vendor in client.model_vendors.list_all(model_id="model_xyz789"):
    print(f"  - {vendor.name}")

// List models for a use case
const { data: models } = await client.useCases.models.list('uc_abc123');
if (models) {
  for (const model of models.items) {
    console.log(`  - ${model.name}`);
  }
}

// List vendors for a model
const { data: vendors } = await client.models.vendors.list('model_xyz789');
if (vendors) {
  for (const vendor of vendors.items) {
    console.log(`  - ${vendor.name}`);
  }
}

Best Practices

Choose an Appropriate Page Size

Python
TypeScript

# For quick overviews, use smaller pages
response = client.use_cases.list(page_limit=10)

# For bulk operations, use larger pages
for uc in client.use_cases.list_all(page_size=100):
    process(uc)

// For quick overviews, use smaller pages
const { data } = await client.useCases.list({ pageLimit: 10 });

// For bulk operations, use larger pages
const allUseCases = await listAll((cursor) =>
  client.useCases.list({ pageLimit: 100, pageAfter: cursor })
);
allUseCases.forEach(process);

Handle Empty Results

Python
TypeScript

response = client.use_cases.list()

if not response.items:
    print("No use cases found")
else:
    for uc in response.items:
        print(uc.name)

const { data, error } = await client.useCases.list();

if (error) {
  console.error('Request failed:', error.status);
} else if (data.items.length === 0) {
  console.log('No use cases found');
} else {
  for (const uc of data.items) {
    console.log(uc.name);
  }
}

Early Exit

Break out of iteration when you've found what you need:

Python
TypeScript

target_name = "Production Model"

for model in client.models.list_all():
    if model.name == target_name:
        print(f"Found: {model.id}")
        break

const targetName = 'Production Model';
let cursor: string | undefined;

outer:
while (true) {
  const { data, error } = await client.models.list({ pageAfter: cursor });
  if (error || !data) break;

  for (const model of data.items) {
    if (model.name === targetName) {
      console.log('Found:', model.id);
      break outer;
    }
  }

  if (!data.pagination.hasMore) break;
  cursor = data.pagination.nextCursor ?? undefined;
}

Response Structure

Python
TypeScript

response = client.use_cases.list(page_limit=10)

# Items for this page
response.items  # List[UseCaseResponse]

# Pagination metadata
response.pagination.has_more      # bool
response.pagination.next_cursor   # str | None
response.pagination.total_count   # int | None (if available)

const { data, error } = await client.useCases.list({ pageLimit: 10 });

if (!error) {
  // Items for this page
  data.items;  // UseCaseResponse[]

  // Pagination metadata
  data.pagination.hasMore;      // boolean | undefined
  data.pagination.nextCursor;   // string | null | undefined
  data.pagination.totalCount;   // number | null | undefined
}

Next Steps

Learn about Error Handling
Explore Async Operations

Basic Pagination​

Pagination Parameters​

Manual Pagination​

Automatic Pagination​

Collecting All Items​

Memory-Efficient Processing​

Async Pagination​

Pagination for Relationships​

Best Practices​

Choose an Appropriate Page Size​

Handle Empty Results​

Early Exit​

Response Structure​

Next Steps​