Long Polling

Long Polling is an asynchronous workflow that lets your application retrieve compression results by repeatedly checking job status until processing completes. It's a good fit when you cannot receive inbound HTTP requests (for example, local development, restricted networks, or environments where hosting a webhook endpoint is not practical).

Workflow Overview

1. Submit a request (File Upload or File Fetch).
2. Receive an immediate acknowledgement containing a job id and initial status (e.g., enqueued).
3. Poll the job status endpoint until it reaches a terminal state.
4. Once completed, use the returned result payload (including the output url) exactly like a synchronous response.

Submit an Async Job

When a request is handled asynchronously, the API returns an acknowledgement like:

{
  "id": "38a8bb5e-7b50-4a22-a0a6-b9602fccb225",
  "status": "enqueued"
}

Store the id value — this is what you use for subsequent status checks.

Poll for Status

Query the job status endpoint using the job id:

GET https://api.compressor.app/1.0/jobs/{id}

Responses return the current status and (when available) the final result.

Example (still processing):

{
  "id": "38a8bb5e-7b50-4a22-a0a6-b9602fccb225",
  "status": "processing"
}

Example (completed successfully):

{
  "id": "38a8bb5e-7b50-4a22-a0a6-b9602fccb225",
  "status": "completed",
  "url": "https://api.compressor.app/1765712100/38a8bb5e-7b50-4a22-a0a6-b9602fccb225/output.mp4",
  "input": {
    "name": "input.mp4",
    "type": "video",
    "format": "mp4",
    "mime": "video/mp4",
    "size": 84510234,
    "sha1": "aad2a74bc3c322b2a1db120ed0d8804c1b23e9bb"
  },
  "output": {
    "name": "output.mp4",
    "type": "video",
    "format": "mp4",
    "mime": "video/mp4",
    "size": 31244109,
    "sha1": "0fa123704be4c84af340f3f6ede800ba254344c2"
  }
}

Example (failed):

{
  "success": false,
  "id": "0c3a7bf4-9986-4f4a-bb72-155e9111c5de",
  "status": "failed",
  "message": "Incoming request body does not contain a valid JSON data"
}

Polling Strategy

To avoid unnecessary traffic and rate-limit pressure, poll with a sensible backoff strategy:

• Start with a short delay (e.g., 1–2 seconds)
• Increase the interval gradually while the job remains enqueued or processing
• Stop polling once the job is in a terminal state (completed or failed)

If the API returns a Retry-After header on status requests, your client should respect it.

Terminal States

A job is finished when its status is one of:

• completed — processing succeeded and the output URL is available
• failed — processing did not complete successfully and an error payload is returned

Other intermediate statuses (such as enqueued or processing) indicate that work is still ongoing.

Authentication

Status checks use the same authentication as all other endpoints (HTTP Basic Auth or Bearer Auth). The job status endpoint does not require any additional credentials beyond your API key.

Notes

• Long Polling is a pull-based alternative to Webhooks and does not require inbound connectivity.
• Polling clients should be idempotent and tolerate transient network errors.
• For production systems, Webhooks are typically preferred to reduce latency and avoid repeated polling requests.