Async Job Status API Documentation¶

Overview¶

The Status API retrieves the status and result of asynchronous jobs submitted via other endpoints (e.g., JSON Formatter, File Upload processors).
Each job is identified by a unique job_id, returned at submission time.
This API allows clients to poll job completion, retrieve results, and monitor failures.

Base URL:
https://api.apidatatools.com/jobs/{job_id}

Endpoint (GET)¶

GET https://api.apidatatools.com/jobs/{job_id}

Headers¶

Header	Description	Required	Example
`x-api-key`	User’s API key for authorization	Yes	`abcdef1234567890`

Path Parameter¶

Parameter	Description	Required	Example
`job_id`	The unique identifier for your async job.	Yes	`a1b2c3d4-e5f6-7890-abcd-ef1234567890`

Example Requests¶

Retrieve job status using curl¶

curl -X GET "https://api.apidatatools.com/status-api/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-api-key: your_api_key"

Using Postman¶

Create a new GET request.
URL: https://api.apidatatools.com/status-api/{job_id}
In the Headers tab, add a key x-api-key with your API key.
Replace {job_id} with your actual ID.
Send the request.

Example Response - Queued¶

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "queued",
  "created_at": 1712345678,
  "updated_at": 1712345678,
  "message": "Your job is being processed.",
  "retry_after": 2
}

Explanation¶

When the job is still running or queued, the API returns a soft polling hint (retry_after in seconds).
You can repeat your request after that duration.

Example Response - Success¶

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "success",
  "created_at": 1712345678,
  "updated_at": 1712345689,
  "result": {
    "request_id": "b7f9e1c3-8d2a-4e6f-9a3c-0d8e7f2b9a1f",
    "status": "success",
    "file": "https://downloads.apidatatools.com/apidatatools_convert_abc123.json",
    "preview": "{\n  \"name\": \"John\",\n  \"age\": 30\n}"
  }
}

Explanation¶

The result field contains the same payload the original async job would have returned if processed synchronously.
Once the job reaches "success", it’s ready for download or further processing.

Example Response - Failed¶

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "failed",
  "created_at": 1712345678,
  "updated_at": 1712345689,
  "error": {
    "code": "INVALID_JSON",
    "message": "JSON validation failed.",
    "details": {
      "line": 2,
      "column": 5
    }
  }
}

Explanation¶

Failed jobs return structured error details, including line or column references when applicable.
The error.code aligns with the error type of the API that generated this job.

Example with Python¶

import requests

job_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
url = f"https://api.apidatatools.com/status-api/{job_id}"
headers = {"x-api-key": "your_api_key"}

response = requests.get(url, headers=headers)
data = response.json()

if data["status"] == "success":
    print("Job complete:", data["result"])
elif data["status"] == "failed":
    print("Error:", data["error"])
else:
    print(data["message"], "- retry after", data.get("retry_after", 5), "seconds")

Example with JavaScript (fetch)¶

async function checkStatus(jobId) {
  const res = await fetch(`https://api.apidatatools.com/status-api/${jobId}`, {
    method: "GET",
    headers: {
      "x-api-key": "your_api_key"
    }
  });

  const data = await res.json();

  switch (data.status) {
    case "success":
      console.log("Job completed successfully:", data.result);
      break;
    case "failed":
      console.error("Job failed:", data.error);
      break;
    default:
      console.log(data.message);
      setTimeout(() => checkStatus(jobId), data.retry_after * 1000);
  }
}

checkStatus("a1b2c3d4-e5f6-7890-abcd-ef1234567890");

Error Handling¶

Error Code	HTTP Status	Description	Example
`INVALID_JOB_ID`	400	`job_id` missing or invalid format	`{"status":"error","error":"INVALID_JOB_ID","details":{"message":"job_id is required"}}`
`UNAUTHORIZED`	401	Missing or invalid auth context	`{"status":"error","error":"UNAUTHORIZED","details":{"message":"Missing authorizer context"}}`
`FORBIDDEN`	403	Job belongs to another user	`{"status":"error","error":"FORBIDDEN","details":{"message":"Access denied"}}`
`JOB_NOT_FOUND`	404	Job not found or deleted	`{"status":"error","error":"JOB_NOT_FOUND","details":{"message":"Job not found"}}`
`RATE_LIMITED`	429	Too many requests per minute	`{"status":"error","error":"RATE_LIMITED","details":{"message":"Too many status requests. Please slow down."}}`
`INTERNAL_ERROR`	500	Unexpected DynamoDB or API error	`{"status":"error","error":"INTERNAL_ERROR","details":{"message":"Failed to process job"}}`

Rate Limiting Note¶

Rate limiting does not consume billing quota.

Notes for Developers¶

This endpoint helps clients safely poll long-running jobs.
Always check the status field: values can be "queued", "processing", "success", or "failed".
Include a pause of retry_after seconds between status checks.
The result object returned on success matches the output schema of the corresponding async API.