Skip to main content
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:
  1. Fetches the first page from the API
  2. Checks for links.next in the response
  3. Fetches subsequent pages until links.next is empty
  4. Aggregates results into a single response using reflection
  5. 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
asc analytics reports --stream --paginate
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
  RESPONSE=$(asc apps list --limit 50 ${NEXT:+--next "$NEXT"} --output json)
  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 beta-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.