Bulk API

Overview

Bulk API endpoints allow performing multiple operations in a single request, reducing overhead and improving performance. Based on docs/bulk_api.md from the AWX source.

Available Endpoints

Endpoint	Description
`/api/v2/bulk/job_launch/`	Launch multiple jobs in one request
`/api/v2/bulk/host_create/`	Create multiple hosts
`/api/v2/bulk/host_delete/`	Delete multiple hosts

Bulk Job Launch

Launch multiple jobs in a single request. AWX creates a workflow job with individual jobs as nodes.

Endpoint

POST /api/v2/bulk/job_launch/

Basic Example

curl -X POST \
  https://awx.example.com/api/v2/bulk/job_launch/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bulk Deploy",
    "jobs": [
      {"unified_job_template": 7},
      {"unified_job_template": 8},
      {"unified_job_template": 9}
    ]
  }'

string

required

Name for the bulk job (workflow)

array

required

Array of job definitions

integer

Organization to assign to workflow (required for users in multiple orgs)

Job-Level Prompts

curl -X POST \
  https://awx.example.com/api/v2/bulk/job_launch/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bulk Deploy with Prompts",
    "jobs": [
      {
        "unified_job_template": 11,
        "limit": "kansas",
        "credentials": [1],
        "inventory": 1
      },
      {
        "unified_job_template": 12,
        "limit": "texas"
      }
    ]
  }'

Promptable fields (if enabled on template):

inventory
credentials (array)
limit
job_type
verbosity
job_tags
skip_tags
extra_vars
diff_mode
scm_branch

Instance groups are not supported at the node level and will be ignored.

Workflow-Level Prompts

Provide defaults for all jobs:

curl -X POST \
  https://awx.example.com/api/v2/bulk/job_launch/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bulk Deploy",
    "jobs": [
      {"unified_job_template": 11, "limit": "kansas"},
      {"unified_job_template": 12},
      {"unified_job_template": 13}
    ],
    "inventory": 2
  }'

The inventory: 2 applies to templates 11, 12, and 13 where inventory is promptable.

Limits

Maximum jobs per request is controlled by BULK_JOB_MAX_LAUNCH setting.

RBAC

Who can bulk launch?

Any authenticated user
Requires execute or update permission on each template

Organization assignment:

Superusers: Can assign any organization or none
Single org users: Organization auto-assigned
Multi-org users: Must specify organization

curl -X POST \
  https://awx.example.com/api/v2/bulk/job_launch/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bulk Job Launch",
    "organization": 2,
    "jobs": [
      {"unified_job_template": 12},
      {"unified_job_template": 13}
    ]
  }'

Who can see bulk jobs?

System admins and org admins see workflow in job lists
Regular users see only individual jobs, not the parent workflow

Response

Returns a workflow job:

{
  "id": 50,
  "type": "workflow_job",
  "url": "/api/v2/workflow_jobs/50/",
  "name": "Bulk Deploy",
  "status": "pending",
  "workflow_nodes": "/api/v2/workflow_jobs/50/workflow_nodes/"
}

Bulk Host Create

Create multiple hosts in an inventory with one request.

Endpoint

POST /api/v2/bulk/host_create/

Example

curl -X POST \
  https://awx.example.com/api/v2/bulk/host_create/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inventory": 1,
    "hosts": [
      {
        "name": "host1.example.com",
        "variables": "ansible_connection: local"
      },
      {
        "name": "host2.example.com",
        "variables": "ansible_host: 192.168.1.10"
      },
      {
        "name": "host3.example.com"
      }
    ]
  }'

integer

required

Inventory ID

array

required

Array of host objects with name and optional variables

Limits

Maximum hosts per request: BULK_HOST_MAX_CREATE (default: 100)
Maximum payload size: 1MB (nginx limit)

Response

{
  "hosts": [
    {"id": 101, "name": "host1.example.com"},
    {"id": 102, "name": "host2.example.com"},
    {"id": 103, "name": "host3.example.com"}
  ]
}

Bulk Host Delete

Delete multiple hosts in one request.

Endpoint

POST /api/v2/bulk/host_delete/

Example

curl -X POST \
  https://awx.example.com/api/v2/bulk/host_delete/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "hosts": [3, 4, 5, 6, 7, 8, 9, 10]
  }'

array

required

Array of host IDs to delete

Limits

Maximum hosts per request: BULK_HOST_MAX_DELETE (default: 250)
Maximum payload size: 1MB (nginx limit)

Response

{
  "deleted": 8
}

Performance Benefits

Bulk APIs prevent:

Overwhelming AWX with rapid individual requests
504 timeout errors from excessive concurrency
Excessive database queries and connections
Rate limiting issues

Use Bulk Job Launch

Instead of launching 100 jobs individually, use bulk launch to create a single workflow.

Batch Host Operations

When adding/removing many hosts, use bulk endpoints instead of individual API calls.

Mind the Limits

Respect BULK_*_MAX_* settings to avoid errors. Break large operations into batches.

Complete Example

import requests
import json

base_url = "https://awx.example.com/api/v2"
token = "YOUR_TOKEN"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# Bulk job launch
job_templates = [10, 11, 12, 13, 14]
bulk_jobs = {
    "name": "Deploy All Services",
    "jobs": [
        {"unified_job_template": tid, "limit": "production"}
        for tid in job_templates
    ],
    "inventory": 3
}

response = requests.post(
    f"{base_url}/bulk/job_launch/",
    headers=headers,
    data=json.dumps(bulk_jobs)
)

if response.status_code in [201, 202]:
    workflow = response.json()
    print(f"Launched bulk job workflow {workflow['id']}")
else:
    print(f"Error: {response.status_code}")
    print(response.json())

# Bulk host create
hosts_to_add = [
    {"name": f"web{i:02d}.example.com", "variables": f"server_id: {i}"}
    for i in range(1, 21)
]

bulk_hosts = {
    "inventory": 1,
    "hosts": hosts_to_add
}

response = requests.post(
    f"{base_url}/bulk/host_create/",
    headers=headers,
    data=json.dumps(bulk_hosts)
)

if response.status_code == 201:
    result = response.json()
    print(f"Created {len(result['hosts'])} hosts")

Getting Started

Core Resources

Job Management

Advanced

Overview

Available Endpoints

Bulk Job Launch

Endpoint

Basic Example

Job-Level Prompts

Workflow-Level Prompts

Limits

RBAC

Response

Bulk Host Create

Endpoint

Example

Limits

Response

Bulk Host Delete

Endpoint

Example

Limits

Response

Performance Benefits

Complete Example

​Overview

​Available Endpoints

​Bulk Job Launch

​Endpoint

​Basic Example

​Job-Level Prompts

​Workflow-Level Prompts

​Limits

​RBAC

​Response

​Bulk Host Create

​Endpoint

​Example

​Limits

​Response

​Bulk Host Delete

​Endpoint

​Example

​Limits

​Response

​Performance Benefits

​Complete Example

Overview

Available Endpoints

Bulk Job Launch

Endpoint

Basic Example

Job-Level Prompts

Workflow-Level Prompts

Limits

RBAC

Response

Bulk Host Create

Endpoint

Example

Limits

Response

Bulk Host Delete

Endpoint

Example

Limits

Response

Performance Benefits

Complete Example