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://api.x.com/2/compliance/jobs/1234567890/upload?token=...",
    "upload_expires_at": "2024-01-15T10:15:00.000Z",
    "download_url": "https://api.x.com/2/compliance/jobs/1234567890/download?token=...",
    "download_expires_at": "2024-01-22T10:00:00.000Z",
    "created_at": "2024-01-15T10:00:00.000Z"
  }
}

Save the upload_url and download_url for the next steps. Both are signed, single-purpose URLs tied to this job: the upload_url expires about 15 minutes after job creation, and the download_url about 7 days after. If an upload URL expires before you use it, cancel the job and create a new one.

You can have one active (created or in_progress) job per job type at a time. Creating a second one returns 409 Conflict until the first completes, fails, or is canceled.

Prepare your data file

Create a plain-text file with one numeric ID per line (up to 1 GiB):

Save as ids.txt. Lines that are not valid IDs are reported in the results as error records rather than failing the whole job.

Upload your data

Upload the file to the provided upload_url with a single PUT, authenticating with the same Bearer token used to create the job:

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

Unlike the previous Google Cloud Storage-based flow, upload and download URLs now require your Authorization header in addition to the signed token embedded in the URL.

A successful upload returns 200 OK and the job moves to in_progress. An expired token returns 403 with a problem+json body.

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 (like the upload, this requires your Bearer token):

curl "DOWNLOAD_URL_FROM_RESPONSE" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -o results.ndjson

Result format (newline-delimited JSON, one object per line):

{"id": "1234567890", "action": "delete", "created_at": "2024-01-10T12:00:00.000Z", "redacted_at": "2024-01-12T08:30:00.000Z", "deleted_at": "2024-01-12T08:30:00.000Z", "reason": "deleted"}
{"id": "1234567891", "action": "rehydrate", "created_at": "2024-01-10T12:00:00.000Z", "redacted_at": "2024-01-13T14:20:00.000Z", "reason": "tweet_edited"}
{"id": "1234567892", "action": "scrub_geo", "created_at": "2018-05-27T10:00:00.000Z", "redacted_at": "2019-06-20T02:00:00.000Z", "reason": "geo_scrubbed"}
{"id": "not_a_valid_id", "error": "invalid_id"}

Only IDs with compliance events appear in the results. An ID absent from the results has no compliance event — your stored copy is fine. Invalid submitted lines come back as {"id": ..., "error": "invalid_id"} records. redacted_at can be null when the original event predates timestamp tracking.

Compliance actions

Post compliance events

Action	Reason	What to do
`delete`	`deleted`	Delete your stored copy — the Post was deleted
`delete`	`protected`	Delete your stored copy — the author’s account became protected
`delete`	`deactivated`	Delete your stored copy — the author’s account was deactivated
`delete`	`suspended`	Delete your stored copy — the author’s account was suspended
`rehydrate`	`tweet_edited`	Re-fetch the Post — it was edited and your copy is a stale revision
`scrub_geo`	`geo_scrubbed`	Delete stored geo data for the Post — the author removed location data

User compliance events

Action	Reason	What to do
`delete`	`deleted`	Delete stored data for the account — it was deleted
`delete`	`protected`	Delete stored data — the account became protected
`delete`	`deactivated`	Delete stored data — the account was deactivated
`delete`	`suspended`	Delete stored data — the account was suspended

When multiple events apply to the same ID, the results carry the highest-impact one: delete outranks rehydrate, which outranks scrub_geo.

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"

Cancel a job

Cancel a job that is awaiting upload or still processing (frees the one-active-job slot for its type):

curl -X DELETE "https://api.x.com/2/compliance/jobs/1234567890" \
  -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

Overview

Posts

Articles

Users

Direct Messages

Likes

Lists

Spaces

Communities

Community Notes

Trends

News

Media

X Activity

Usage

Stream Connections

Compliance

Webhooks

Quickstart

Compliance actions

List all jobs

Cancel a job

Next steps

Integration guide

Compliance streams

API Reference

​Compliance actions

​List all jobs

​Cancel a job

​Next steps

Integration guide

Compliance streams

API Reference

Compliance actions

List all jobs

Cancel a job

Next steps