Quickstart

This guide walks you through creating a batch compliance job to check the compliance status of Posts or users.

PrerequisitesBefore you begin, you’ll need:

A developer account with an approved App
Your App’s Bearer Token

Create a job

Create a new compliance job specifying the type (tweets or users):

cURL
Python

curl -X POST "https://api.x.com/2/compliance/jobs" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "tweets",
    "name": "my-compliance-job"
  }'

import requests

bearer_token = "YOUR_BEARER_TOKEN"

url = "https://api.x.com/2/compliance/jobs"
headers = {
    "Authorization": f"Bearer {bearer_token}",
    "Content-Type": "application/json"
}
payload = {
    "type": "tweets",
    "name": "my-compliance-job"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Response:

{
  "data": {
    "id": "1234567890",
    "type": "tweets",
    "name": "my-compliance-job",
    "status": "created",
    "upload_url": "https://storage.googleapis.com/...",
    "download_url": "https://storage.googleapis.com/...",
    "created_at": "2024-01-15T10:00:00.000Z"
  }
}

Save the upload_url and download_url for the next steps.

Prepare your data file

Create a text file with one ID per line:

Save as ids.txt.

Upload your data

Upload the file to the provided upload_url:

curl -X PUT "UPLOAD_URL_FROM_RESPONSE" \
  -H "Content-Type: text/plain" \
  --data-binary @ids.txt

Check job status

Poll the job status until it’s complete:

curl "https://api.x.com/2/compliance/jobs/1234567890" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Job statuses:

Status	Description
`created`	Job created, awaiting upload
`in_progress`	Processing data
`complete`	Results ready for download
`failed`	Job failed
`expired`	Job expired before completion

Download results

Once status is complete, download from the download_url:

curl "DOWNLOAD_URL_FROM_RESPONSE" -o results.json

Result format (one JSON object per line):

{"id": "1234567890", "action": "delete", "created_at": "2024-01-10T12:00:00.000Z", "redacted_at": "2024-01-12T08:30:00.000Z", "reason": "deleted"}
{"id": "1234567891", "action": "delete", "created_at": "2024-01-10T12:00:00.000Z", "redacted_at": "2024-01-13T14:20:00.000Z", "reason": "suspended"}

Only IDs with compliance events appear in the results. IDs not in the results are still valid.

Compliance actions

Post compliance events

Action	Reason	Description
`delete`	`deleted`	Post was deleted
`delete`	`bounced`	Post failed compliance check
`delete`	`protected`	Account became protected
`delete`	`suspended`	Account was suspended
`delete`	`scrub_geo`	Geo data was removed

User compliance events

Action	Reason	Description
`delete`	`deleted`	Account was deleted
`delete`	`suspended`	Account was suspended
`delete`	`protected`	Account became protected
`delete`	`deactivated`	Account was deactivated

List all jobs

Get all compliance jobs for your App:

curl "https://api.x.com/2/compliance/jobs?type=tweets" \
  -H "Authorization: Bearer $BEARER_TOKEN"

Next steps

Integration guide

Key concepts and best practices

Compliance streams

Real-time compliance events

API Reference

Full endpoint documentation

​Compliance actions

​List all jobs

​Next steps

Integration guide

Compliance streams

API Reference

Compliance actions

List all jobs

Next steps