Skip to main content

​
Overview

AWX API list endpoints return paginated responses to manage large datasets efficiently. The pagination implementation is defined in awx/api/pagination.py.

​
Default Pagination

By default, AWX uses page number pagination with the following characteristics:
  • Default page size: Based on DRF settings
  • Maximum page size: Controlled by MAX_PAGE_SIZE setting
  • Page query parameter: page
  • Page size query parameter: page_size

​
Paginated Response Structure

{
  "count": 150,
  "next": "https://awx.example.com/api/v2/job_templates/?page=2",
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "Deploy Application",
      "description": "Deploy app to production"
    },
    {
      "id": 2,
      "name": "Backup Database",
      "description": "Daily database backup"
    }
  ]
}
​
count
integer
Total number of items across all pages
​
next
string
URL to the next page (null if last page)
​
previous
string
URL to the previous page (null if first page)
​
results
array
Array of resource objects for the current page

​
Query Parameters

​
Page Number

Navigate to a specific page: 
curl -X GET \
  "https://awx.example.com/api/v2/job_templates/?page=2" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Page Size

Control the number of items per page: 
curl -X GET \
  "https://awx.example.com/api/v2/job_templates/?page_size=50" \
  -H "Authorization: Bearer YOUR_TOKEN"
​
page
integer
default:"1"
Page number to retrieve
​
page_size
integer
Number of results per page (max: MAX_PAGE_SIZE setting)

​
Maximum Page Size

If you request a page_size larger than the configured MAX_PAGE_SIZE, it will be automatically capped: 
# Request 1000 items, but only MAX_PAGE_SIZE returned
curl -X GET \
  "https://awx.example.com/api/v2/inventories/?page_size=1000" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Disabled Count Pagination

For large datasets, counting all results can be expensive. Use count_disabled to skip counting: 
curl -X GET \
  "https://awx.example.com/api/v2/job_events/?count_disabled=1" \
  -H "Authorization: Bearer YOUR_TOKEN"
​
count_disabled
boolean
Skip counting total results for performance
With count_disabled=1, the response structure changes: 
{
  "results": [
    {
      "id": 1,
      "event": "playbook_on_start"
    }
  ]
}
The count field is omitted and a fixed value is used internally to determine pagination

​
Limit Pagination

For event endpoints like job events, you can use limit-based pagination instead: 
curl -X GET \
  "https://awx.example.com/api/v2/jobs/123/job_events/?limit=100" \
  -H "Authorization: Bearer YOUR_TOKEN"
​
limit
integer
Maximum number of results to return (used by UnifiedJobEventPagination)
Response with limit pagination: 
{
  "results": [
    {"id": 1, "event": "runner_on_start"},
    {"id": 2, "event": "runner_on_ok"}
  ]
}

​
Pagination Classes

AWX uses different pagination classes based on the endpoint:

​
Pagination (Default)

Used by most list endpoints:
  • Page-based navigation
  • Configurable page size
  • Full result count

​
LimitPagination

Used for simple result limiting:
  • No page navigation
  • Just limits result count
  • Returns results array only

​
UnifiedJobEventPagination

Used for job event endpoints:
  • Supports both page and limit parameters
  • Automatically switches based on query params
  • Optimized for streaming events

​
Iterating Through Pages

​
Python Example

import requests

base_url = "https://awx.example.com/api/v2/job_templates/"
headers = {"Authorization": "Bearer YOUR_TOKEN"}

all_templates = []
url = base_url

while url:
    response = requests.get(url, headers=headers)
    data = response.json()
    
    all_templates.extend(data['results'])
    url = data.get('next')

print(f"Retrieved {len(all_templates)} templates")

​
Bash Example

#!/bin/bash

BASE_URL="https://awx.example.com/api/v2/inventories/"
TOKEN="YOUR_TOKEN"
url="$BASE_URL"

while [ "$url" != "null" ] && [ -n "$url" ]; do
    response=$(curl -s -H "Authorization: Bearer $TOKEN" "$url")
    
    # Process results
    echo "$response" | jq '.results[]'
    
    # Get next URL
    url=$(echo "$response" | jq -r '.next')
done

​
Combining with Filtering and Ordering

Pagination works seamlessly with filtering and ordering: 
curl -X GET \
  "https://awx.example.com/api/v2/jobs/?status=successful&order_by=-created&page_size=20&page=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Performance Considerations

Balance between number of requests and response size. Too small = many requests, too large = slow responses.
When iterating through all results, skip counting to improve performance:
?count_disabled=1&page_size=200
If data doesn’t change frequently, cache paginated results to reduce API calls.
For job events and similar resources, use limit instead of pagination:
/api/v2/jobs/123/job_events/?limit=1000

​
Error Handling

​
Invalid Page Number

{
  "detail": "Invalid page."
}
Returned when requesting a page beyond the last page.

​
Invalid Page Size

Excessive page sizes are automatically capped to MAX_PAGE_SIZE.

​
Examples

​
Get First Page with Custom Size

curl -X GET \
  "https://awx.example.com/api/v2/organizations/?page=1&page_size=25" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Get All Job Events with Limit

curl -X GET \
  "https://awx.example.com/api/v2/jobs/456/job_events/?limit=500" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Paginate Without Count

curl -X GET \
  "https://awx.example.com/api/v2/activity_stream/?count_disabled=1&page_size=100" \
  -H "Authorization: Bearer YOUR_TOKEN"
Pagination behavior is controlled by Django settings:
  • MAX_PAGE_SIZE - Maximum allowed page size
  • PAGE_SIZE - Default page size (DRF setting)
Check your AWX configuration: 
curl -X GET \
  "https://awx.example.com/api/v2/config/" \
  -H "Authorization: Bearer YOUR_TOKEN"

Build docs developers (and LLMs) love

Get started for freeTalk to us