Pagination

Fetch all pages automatically with —paginate or control pagination manually for memory-efficient streaming.

The App Store Connect API returns large result sets in pages. The CLI provides automatic pagination to fetch all results with a single flag.

Automatic Pagination

Use the --paginate flag to fetch all pages automatically:

asc apps list --paginate

Without --paginate, the CLI returns only the first page (default limit varies by endpoint, typically 50-200 items).

The --paginate flag fetches all pages into memory before rendering output. For very large result sets, use manual pagination instead.

Manual Pagination

Control page-by-page fetching with --limit and --next:

# Get first page with custom limit
asc apps list --limit 10 --output json

# Response includes links.next URL
{
  "data": [...],
  "links": {
    "next": "https://api.appstoreconnect.apple.com/v1/apps?cursor=..."
  }
}

# Fetch next page using the URL
asc apps list --next "https://api.appstoreconnect.apple.com/v1/apps?cursor=..."

The --next URL must be a valid App Store Connect API URL (https://api.appstoreconnect.apple.com). The CLI validates the URL for security.

How Pagination Works

The CLI uses a generic pagination system (internal/asc/client_pagination.go) that:

Fetches the first page from the API
Checks for links.next in the response
Fetches subsequent pages until links.next is empty
Aggregates results into a single response using reflection
Detects cycles to prevent infinite loops on repeated pagination URLs

Pagination Interface

All paginated responses implement:

type PaginatedResponse interface {
    GetLinks() *Links
    GetData() any
}

The PaginateAll function works with any response type that follows this interface.

Memory Considerations

Buffered (Default)

With --paginate, all pages are buffered in memory:

# Fetches all pages into memory, then renders
asc apps list --paginate --output table

Use when:

Result set is reasonably sized (< 10,000 items)
You need table or markdown output
You want a single aggregated result

Streaming (Advanced)

For very large datasets, some commands support --stream with --paginate:

# Emits NDJSON (newline-delimited JSON) page-by-page for very large result sets
asc subscriptions pricing price-points list --subscription-id "SUB_ID" --paginate --stream

Each page is printed as a separate JSON line:

{"data":[...],"links":{"next":"..."}}
{"data":[...],"links":{"next":"..."}}
{"data":[...],"links":{}}

Use when:

Result set is very large (> 10,000 items)
You need to process results incrementally
Memory usage is a concern

Streaming mode only works with JSON output. Table and markdown formats require buffering all results.

Pagination Limits

API Limits

The App Store Connect API enforces maximum page sizes per endpoint:

Apps: 200
Builds: 200
Beta Testers: 200
Analytics: 100

The CLI automatically uses the maximum allowed limit when --paginate is set.

Setting Custom Limits

Control the page size with --limit:

# Fetch 10 items per page (useful for testing)
asc builds list --app APP_ID --limit 10 --paginate

Smaller limits result in more API requests but may reduce memory usage slightly.

Error Handling

If a page fetch fails mid-pagination:

asc apps list --paginate

Behavior:

Pages fetched before the error are returned
The error is reported with the page number: page 3: unauthorized
Exit code reflects the error (see Error Handling)

Cycle Detection

The CLI detects repeated links.next URLs to prevent infinite loops:

# If the API returns the same next URL twice
asc apps list --paginate
# Error: page 5: detected repeated pagination URL

Examples

Fetch All Apps

asc apps list --paginate --output json > all_apps.json

Fetch All Builds for an App

asc builds list --app APP_ID --paginate

Manual Pagination Loop (Shell Script)

#!/bin/bash
NEXT=""
while true; do
  if [ -n "$NEXT" ]; then
    RESPONSE=$(asc apps list --limit 50 --next "$NEXT" --output json)
  else
    RESPONSE=$(asc apps list --limit 50 --output json)
  fi
  echo "$RESPONSE" | jq '.data[] | .attributes.name'
  
  NEXT=$(echo "$RESPONSE" | jq -r '.links.next // empty')
  if [ -z "$NEXT" ]; then
    break
  fi
done

Count All Beta Testers

asc testflight testers list --paginate --output json | jq '.data | length'

Implementation Details

The pagination system uses reflection to handle any response type:

// From internal/asc/client_pagination.go
func PaginateAll(
    ctx context.Context,
    firstPage PaginatedResponse,
    fetchNext PaginateFunc,
) (PaginatedResponse, error)

Key features:

Type-safe aggregation using reflection on the Data field
Cycle detection with a seenNext map
Type validation ensures all pages match the first page’s type
Context support for cancellation and timeouts

Spinner Indicator

When --paginate is used in an interactive terminal, a spinner appears on stderr:

asc apps list --paginate
# stderr: ⠋ Fetching...

The spinner is automatically hidden in non-interactive contexts (pipes, CI).

Best Practices

Use --paginate by Default

Always use --paginate unless you specifically want only the first page.

Combine with Filters

Filter before paginating to reduce API calls: --filter[platform]=IOS --paginate

Save JSON Output

Cache paginated results to avoid repeated API calls during development.

Monitor Rate Limits

Paginating large datasets consumes API rate limits. Use --limit to control request frequency.

Output Formats - How pagination interacts with different output formats
Error Handling - Handling errors during pagination
Filtering & Sorting - Reduce pagination needs with filters

Getting Started

Core Concepts

Guides

CI/CD Integration

Configuration

Pagination

Memory Considerations

Buffered (Default)

Streaming (Advanced)

API Limits

Setting Custom Limits

Error Handling

Cycle Detection

Examples

Fetch All Apps

Fetch All Builds for an App

Count All Beta Testers

Implementation Details

Spinner Indicator

Best Practices

Use --paginate by Default

Combine with Filters

Save JSON Output

Monitor Rate Limits

​Pagination

​Automatic Pagination

​Manual Pagination

​How Pagination Works

​Pagination Interface

​Memory Considerations

​Buffered (Default)

​Streaming (Advanced)

​Pagination Limits

​API Limits

​Setting Custom Limits

​Error Handling

​Cycle Detection

​Examples

​Fetch All Apps

​Fetch All Builds for an App

​Manual Pagination Loop (Shell Script)

​Count All Beta Testers

​Implementation Details

​Spinner Indicator

​Best Practices

Use --paginate by Default

Combine with Filters

Save JSON Output

Monitor Rate Limits

​Related

Pagination

Automatic Pagination

Manual Pagination

How Pagination Works

Pagination Interface

Memory Considerations

Buffered (Default)

Streaming (Advanced)

Pagination Limits

API Limits

Setting Custom Limits

Error Handling

Cycle Detection

Examples

Fetch All Apps

Fetch All Builds for an App

Manual Pagination Loop (Shell Script)

Count All Beta Testers

Implementation Details

Spinner Indicator

Best Practices

Related