> ## Documentation Index
> Fetch the complete documentation index at: https://developer.pdf.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Background & Job Check

> Checks the [status](#available-status-values) of a background job that was previously created with PDF.co API. Use this API to check the status of your asynchronous API calls.

<Note>
  **Try it live:** [Background & Job Check → API Tester](/api-tester/job-check) — send a real request from your browser.
</Note>

## `POST /v1/job/check`

## Attributes

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

| 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. |

### Available Status Values

* `working` - background job is currently being processed. Check again after a short delay.
* `success` - background job was successfully finished.
* `failed` - background job failed for some reason (see `message` for more details).
* `aborted` - background job was aborted.

<Note>A job id that is not available for your API key does not come back as a status. It returns HTTP `404` — see [Job not found](#job-not-found-http-404).</Note>

## Query parameters

*No query parameters accepted.*

## Responses

| Parameter | Type | Description |
| - | - | - |
| `status` | string | Status of the background job: `working`, `success`, `failed`, or `aborted`. See [Available Status Values](#available-status-values). |
| `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 |

### Job not found (HTTP 404)

If no job associated with your API key exists for the given `jobid`, the request returns HTTP `404` with the message `Job not found` instead of a job status:

```json theme={null}
{
  "errorCode": 404,
  "error": true,
  "message": "Job not found",
  "remainingCredits": 60227,
  "credits": 0
}
```

This happens when the `jobid` was never created under this API key, when it belongs to a different API key, or when the job is no longer available. The API does not distinguish between these cases.

A `404` is final for the API key you used: that key will not start returning a status for this `jobid`, so stop polling with it. If the job was created with a different API key, check it with that key instead. Only `working` means "check again".

## `Example` Payload

<Note>To see the request size limits, please refer to the [Request Size Limits](/api/url-input-and-request-limits#pdf-co-request-size).</Note>

```json theme={null}
{
  "jobid": "6YSZD3U872ZYYFEDMQCQSGEEO8YSF5WA--151-300"
}
```

## `Example` Response

<Note>To see the main response codes, please refer to the [Response Codes](/api/response-codes) page.</Note>

```json theme={null}
{
  "status": "working",
  "remainingCredits": 60227
}
```

## `Example` Response

<Note>To see the main response codes, please refer to the [Response Codes](/api/response-codes) page.</Note>

```json theme={null}
{
  "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
}
```

<Note>
  **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.
</Note>

## Code Samples

<Tabs>
  <Tab title="CURL">
    ```bash theme={null}
    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"
    }'
    ```
  </Tab>

  <Tab title="JavaScript/Node.js">
    ```javascript theme={null}
    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}".`);
              }
          })
      });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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"

    response = requests.post(
        url,
        headers={ "x-api-key": API_KEY, "Content-Type": "application/json" },
        json={ "jobid": jobId }
    )
    if (response.status_code == 200):
        json = response.json()
        print(f"Job status: {json['status']}")
    elif (response.status_code == 404):
        # The job id is not available for this API key. Stop polling.
        print("Job not found")
    else:
        print(f"Request error: {response.status_code} {response.reason}")
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    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();
        }
    }
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    <?

      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;
      }

    ?>
    ```
  </Tab>
</Tabs>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.