Async Jobs

Overview

The AI Detector endpoint supports asynchronous processing. Instead of waiting for the result in the response, you receive a task_id and can either:

• Poll for the result via GET /api/jobs/{task_id}/
• Receive a webhook at your callback_url
• Both — poll and receive a webhook

Submitting an Async Request

Add poll: true and/or callback_url to your detector request:

curl -X POST https://developer-portal.proofademic.ai/api/detector/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "content": "Your text here...",
    "poll": true
  }'

Response (202 Accepted):

{
  "status": "pending",
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "result": null,
  "word_count": 256,
  "credits_remaining": 1744,
  "user": {
    "id": 12345
  }
}

Credits are consumed when the job is accepted.

GET /api/jobs/{task_id}/

Retrieve the status and result of an async job.

Authentication: X-API-Key header

Request

curl https://developer-portal.proofademic.ai/api/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/ \
  -H "X-API-Key: YOUR_API_KEY"

Response — Processing

The job is still running:

{
  "status": "processing",
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "result": null,
  "service_name": null,
  "execution_time": null,
  "word_count": null,
  "credits_remaining": null,
  "user": {
    "id": 12345
  }
}

Response — Success

The job completed successfully:

{
  "status": "success",
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "result": "ai",
  "ai_score": 0.87,
  "items": [...],
  "service_name": "detector_service",
  "execution_time": 1.52,
  "word_count": 256,
  "credits_remaining": 1744,
  "user": {
    "id": 12345
  }
}

Response — Failed

The job failed (credits are refunded automatically):

{
  "status": "failed",
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "result": null,
  "error": "Detector processing failed.",
  "word_count": 256
}

Job Status Values

Important Notes

• Results expire after 1 hour. After that, the endpoint returns 404.
• Only the owner of the job can retrieve the result. Using another user's task_id returns 404.
• Concurrent job limit — The number of pending async jobs you can have at once depends on your plan. If exceeded, new async requests are rejected with 429 Too Many Requests.

Polling Strategy

We recommend polling with exponential backoff:

1st poll:  after 2 seconds
2nd poll:  after 4 seconds
3rd poll:  after 8 seconds
...and so on, up to a maximum of 30 seconds between polls

Webhook Delivery

When using callback_url, the result is POSTed to your URL once the job completes. The payload is the same JSON structure as the polling response.

If you also provided a webhook_secret, it is included in the X-Webhook-Secret header so you can verify the request authenticity.

Webhook delivery is retried up to 3 times with exponential backoff if your server returns an error.