Background & Job Check

Checks the status of a background job that was previously created with PDF.co API. Use this API to check the status of your asynchronous API calls.

Try it live: Background & Job Check → API Tester — send a real request from your browser.

POST /v1/job/check

Attributes

Attributes are case-sensitive and should be inside JSON for POST request. for example: { "url": "https://example.com/file1.pdf" }

Attribute	Type	Required	Default	Description
jobId	string	Yes	-	ID of background that was started asynchronously. To start a new async background job, you should set async to true for API methods.
force	boolean	No	false	Set to true to forcibly check the status of the background job. Intended to be used with really long and heavy background jobs only.

Available Status Values

• working - background job is currently in work or does not exist.
• success - background job was successfully finished.
• failed - background job failed for some reason (see message for more details).
• aborted - background job was aborted.
• unknown - unknown background job id. Available only when force is set to true for input request.

Query parameters

No query parameters accepted.

Responses

Parameter	Type	Description
status	string	Status code of the request (200, 404, 500, etc.). For more information, see Response Codes.
message	string	Message of the request
pageCount	integer	Number of pages in the PDF document.
url	string	Direct URL to the final PDF file stored in S3.
outputLinkValidTill	string	Timestamp indicating when the output link will expire
jobId	string	Identifier for the job request
credits	integer	Number of credits consumed by the request
remainingCredits	integer	Number of credits remaining in the account
jobDuration	integer	Time taken to execute the job in milliseconds
duration	integer	Time taken for the operation in milliseconds

Example Payload

To see the request size limits, please refer to the Request Size Limits.

{
  "jobid": "6YSZD3U872ZYYFEDMQCQSGEEO8YSF5WA--151-300"
}

Example Response

{
  "status": "working",
  "remainingCredits": 60227
}

Example Response

{
  "status": "success",
  "message": "Success",
  "url": "https://pdf-temp-files.s3.us-west-2.amazonaws.com/6YSZD3U872ZYYFEDMQCQSGEEO8YSF5WA--151-300/L8QYIZQ6KZOITCT0PXUNPM6HKYSP5OIO.json?X-Amz-Expires=3600&X-Amz-Security-Token=FwoGZXIvYXdzECcaDAbrXwAd1IYG3nZR5yKCAdcavWT%2BuwTotGsad9asqRzowPa1M4BoIWU0M9FqXNJP8xBIQX1Cn7XTq4ZfpklsxcpGE4WcapfHdooi2uR1QWw4kuUlMGGU92uy7pS0RhaGCEL00ES%2BIb%2F5039yyAFklqfAgDlHvi47I7Pp01y6Ua25RzrZGh6ACOd7le%2BXArnbQs4o4ezNqgYyKD%2FCX1I5ZOS0tu0ND0I%2FUWTHp6OR8He9a0dgVXfiMU7pNkwQqwVVFcM%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIA4NRRSZPHAZTLLKK5/20231114/us-west-2/s3/aws4_request&X-Amz-Date=20231114T134932Z&X-Amz-SignedHeaders=host&X-Amz-Signature=e5553e080a23fb158c0514f99c9f70be0cb74f764933d712ba628110d4079b4c",
  "jobId": "6YSZD3U872ZYYFEDMQCQSGEEO8YSF5WA--151-300",
  "credits": 2,
  "remainingCredits": 1480582,
  "duration": 33
}

Inconsistent URL Encoding in cURL Output: When using cURL to make API requests, the output JSON may show URL characters encoded as Unicode escape sequences. For example, the ampersand character (&) may appear as \u0026 in the cURL output. This is normal JSON encoding behavior and does not affect the validity of the URL. The URL will function correctly when used, as JSON parsers automatically decode these escape sequences. If you’re parsing the response programmatically, your JSON parser will handle this conversion automatically.

Code Samples

CURL

curl --location --request POST 'https://api.pdf.co/v1/job/check' \
--header 'x-api-key: *******************' \
--header 'Content-Type: application/json' \
--data-raw '{
"jobid": "6YSZD3U872ZYYFEDMQCQSGEEO8YSF5WA--151-300"
}'

JavaScript/Node.js

var https = require("https");
  var path = require("path");
  var fs = require("fs");

  // The authentication key (API Key).
  // Get your own by registering at https://app.pdf.co
  const API_KEY = "***********************************";
  const jobId = "{your_job_id}";

  let queryPath = `/v1/job/check`;

  // JSON payload for api request
  let jsonPayload = JSON.stringify({
      jobid: jobId
  });

  let reqOptions = {
      host: "api.pdf.co",
      path: queryPath,
      method: "POST",
      headers: {
          "x-api-key": API_KEY,
          "Content-Type": "application/json",
          "Content-Length": Buffer.byteLength(jsonPayload, 'utf8')
      }
  };

  // Send request
  var postRequest = https.request(reqOptions, (response) => {
      response.on("data", (d) => {
          response.setEncoding("utf8");

          // Parse JSON response
          let data = JSON.parse(d);
          console.log(`Checking Job #${jobId}, Status: ${data.status}, Time: ${new Date().toLocaleString()}`);

          if (data.status == "success") {
              console.log(`Job success!`);
          }
          else {
              console.log(`Operation ended with status: "${data.status}".`);
          }
      })
  });

Python

import os
import requests # pip install requests

# The authentication key (API Key).
# Get your own by registering at https://app.pdf.co
API_KEY = "******************************************"
jobId = "******************************************"

# Base URL for PDF.co Web API requests
BASE_URL = "https://api.pdf.co/v1"

url = f"{BASE_URL}/job/check?jobid={jobId}"

response = requests.get(url, headers={ "x-api-key": API_KEY })
if (response.status_code == 200):
    json = response.json()
    return json["status"]
else:
    print(f"Request error: {response.status_code} {response.reason}")

Java

package com.company;

import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import com.google.gson.JsonPrimitive;
import okhttp3.*;

public class Main
{
    // The authentication key (API Key).
    // Get your own by registering at https://app.pdf.co
    final static String API_KEY = "***********************************";

    public static void main(String[] args) throws IOException
    {
      // Prepare POST request body in JSON format
      JsonObject jsonBody = new JsonObject();
      jsonBody.add("jobid", new JsonPrimitive(jobId));

      RequestBody body = RequestBody.create(MediaType.parse("application/json"), jsonBody.toString());

      // Prepare request to `Job Check` API
      Request request = new Request.Builder()
              .url("https://api.pdf.co/v1/job/check")
              .addHeader("x-api-key", API_KEY) // (!) Set API Key
              .addHeader("Content-Type", "application/json")
              .post(body)
              .build();

      // Execute request
      Response response = webClient.newCall(request).execute();
    }
}

PHP

<?

  function CheckJobStatus($jobId, $apiKey)
  {
      $status = null;

      // Create URL
      $url = "https://api.pdf.co/v1/job/check";

      // Prepare requests params
      $parameters = array();
      $parameters["jobid"] = $jobId;

      // Create Json payload
      $data = json_encode($parameters);

      // Create request
      $curl = curl_init();
      curl_setopt($curl, CURLOPT_HTTPHEADER, array("x-api-key: " . $apiKey, "Content-type: application/json"));
      curl_setopt($curl, CURLOPT_URL, $url);
      curl_setopt($curl, CURLOPT_POST, true);
      curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
      curl_setopt($curl, CURLOPT_POSTFIELDS, $data);

      // Execute request
      $result = curl_exec($curl);

      if (curl_errno($curl) == 0)
      {
          $status_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);

          if ($status_code == 200)
          {
              $json = json_decode($result, true);

              if (!isset($json["error"]) || $json["error"] == false)
              {
                  $status = $json["status"];
              }
              else
              {
                  // Display service reported error
                  echo "<p>Error: " . $json["message"] . "</p>";
              }
          }
          else
          {
              // Display request error
              echo "<p>Status code: " . $status_code . "</p>";
              echo "<p>" . $result . "</p>";
          }
      }
      else
      {
          // Display CURL error
          echo "Error: " . curl_error($curl);
      }

      // Cleanup
      curl_close($curl);

      return $status;
  }

?>