Pagination

All list endpoints in the Transcodely API support pagination to efficiently traverse large result sets. The API uses cursor-based pagination, which provides stable results even as new resources are created or deleted between requests.

Request Parameters

Every list endpoint accepts a pagination object with these fields:

Field	Type	Default	Description
`limit`	`integer`	`20`	Maximum items per page (1-100)
`cursor`	`string`	`""`	Cursor from previous response for next page
`offset`	`integer`	`0`	Alternative to cursor — skip N items

Basic Example

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/List 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{
    "pagination": {
      "limit": 10
    }
  }'

Response Metadata

Every list response includes a pagination object:

Field	Type	Description
`next_cursor`	`string`	Cursor for fetching the next page. Empty if no more pages.
`total_count`	`integer` (optional)	Total number of matching items, if available

{
  "jobs": [ ... ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImpvYl94OXk4ejd3NnY1In0",
    "total_count": 142
  }
}

Cursor-Based Pagination

Cursor pagination is the recommended approach. Pass the next_cursor from the previous response as the cursor in the next request:

Page 1

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/List 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{
    "pagination": { "limit": 10 }
  }'

Response:

{
  "jobs": [ "... 10 jobs ..." ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImpvYl94OXk4ejd3NnY1In0",
    "total_count": 42
  }
}

Page 2

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/List 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{
    "pagination": {
      "limit": 10,
      "cursor": "eyJpZCI6ImpvYl94OXk4ejd3NnY1In0"
    }
  }'

Last Page

When there are no more results, next_cursor is an empty string:

{
  "jobs": [ "... 2 remaining jobs ..." ],
  "pagination": {
    "next_cursor": "",
    "total_count": 42
  }
}

Iterating All Pages

Loop through pages using the cursor returned in each response:

async function getAllJobs(client: JobServiceClient): Promise<Job[]> {
  const allJobs: Job[] = [];
  let cursor = '';

  do {
    const response = await client.list({
      pagination: { limit: 100, cursor },
    });

    allJobs.push(...response.jobs);
    cursor = response.pagination?.next_cursor ?? '';
  } while (cursor !== '');

  return allJobs;
}

def get_all_jobs(client):
    all_jobs = []
    cursor = ""

    while True:
        response = client.list(
            pagination={"limit": 100, "cursor": cursor}
        )
        all_jobs.extend(response.jobs)

        cursor = response.pagination.next_cursor
        if not cursor:
            break

    return all_jobs

func getAllJobs(ctx context.Context, client jobv1connect.JobServiceClient) ([]*jobv1.Job, error) {
	var allJobs []*jobv1.Job
	cursor := ""

	for {
		resp, err := client.List(ctx, connect.NewRequest(&jobv1.ListJobsRequest{
			Pagination: &commonv1.PaginationRequest{
				Limit:  100,
				Cursor: cursor,
			},
		}))
		if err != nil {
			return nil, err
		}

		allJobs = append(allJobs, resp.Msg.Jobs...)
		cursor = resp.Msg.Pagination.NextCursor
		if cursor == "" {
			break
		}
	}

	return allJobs, nil
}

Offset Pagination

As an alternative to cursors, you can use offset-based pagination. This is simpler but less stable — if items are created or deleted between pages, you may see duplicates or skip items.

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/List 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: org_a1b2c3d4e5" 
  -H "Content-Type: application/json" 
  -d '{
    "pagination": { "limit": 10, "offset": 20 }
  }'

Use offset pagination only when you need random access to a specific page (e.g., “jump to page 3”). For sequential traversal, always prefer cursors.

Cursor vs Offset

Feature	Cursor	Offset
Stability	Stable across inserts/deletes	May skip or duplicate items
Performance	Consistent (index-based)	Slower on deep pages
Random access	Not supported	Supported
Recommended for	Sequential iteration, real-time data	Jump-to-page UIs

Best Practices

Use cursor pagination for iterating through results sequentially.
Set limit to the maximum your UI can display — fewer requests means better performance.
Stop when next_cursor is empty — this is the only reliable signal that you have reached the last page.
Do not construct cursors manually — they are opaque tokens. Always use the value returned by the API.
Cache total_count if needed — it may not be available on all endpoints and can be expensive to compute.

#Pagination

#Request Parameters

#Basic Example

#Response Metadata

#Cursor-Based Pagination

#Page 1

#Page 2

#Last Page

#Iterating All Pages

#Offset Pagination

#Cursor vs Offset

#Best Practices