Cancel a Non-Terminal Plangrep Job

Cancel a processing job that has not yet reached a terminal state. Once cancelled, the job transitions to cancelled status and no further processing occurs. Use this endpoint to stop a job that was created in error, is no longer needed, or needs to be restarted with different files.

Authentication

Include your API key as Authorization: Bearer YOUR_API_KEY in the request headers.

Endpoint

POST https://plangrep.com/api/open/v1/jobs/{jobId}/cancel

Path Parameters

jobId

string

required

The unique identifier of the job to cancel. The job must not already be in a terminal state (completed, completed_with_errors, failed, cancelled, or expired).

Request Body

This endpoint takes no request body.

Example Request

curl --request POST \
  --url https://plangrep.com/api/open/v1/jobs/job_01hy3m8qtn2e5r7k9p0w4x1def/cancel \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Accept: application/json"

Response Fields

job

Job

required

The updated job object reflecting the cancelled state.

Show Job object fields

string

required

Unique identifier for the job.

externalId

string | null

Client-supplied correlation ID, or null if none was provided at creation.

status

JobStatus

required

Will be "cancelled" upon a successful response.

projectId

string

required

The ID of the parent project.

limits

object

required

Processing limits that were applied to this job.

Show limits fields

maxDeclaredBytes

integer

required

Maximum total bytes that could be uploaded to this job.

maxFiles

integer

required

Maximum number of files that could be uploaded to this job.

pageCount

integer

required

Total number of pages that had been submitted for processing at the time of cancellation.

successfulPageCount

integer

required

Number of pages successfully processed before cancellation.

billing

object

required

Final billing snapshot. Pages processed before cancellation may have been charged.

files

object[]

required

Metadata for each file that was attached to the job.

resultUrl

string | null

Always null for cancelled jobs — no result is generated.

error

object | null

null for cancellations initiated by the user.

createdAt

string

required

ISO 8601 timestamp of job creation.

updatedAt

string

required

ISO 8601 timestamp of the cancellation event.

completedAt

string | null

ISO 8601 timestamp of when the job was cancelled.

expiresAt

string

required

ISO 8601 timestamp after which the job and its result are no longer accessible.

Example Response

{
  "job": {
    "id": "job_01hy3m8qtn2e5r7k9p0w4x1def",
    "externalId": "order-7890",
    "status": "cancelled",
    "projectId": "proj_01hx9z4kqr8e7m3p5n6w2v0abc",
    "limits": {
      "maxDeclaredBytes": 10000000000,
      "maxFiles": 100
    },
    "pageCount": 204,
    "successfulPageCount": 63,
    "billing": {
      "creditsDebited": 63
    },
    "files": [
      {
        "id": "file_xyz789",
        "fileName": "architectural_drawings.pdf",
        "status": "cancelled"
      }
    ],
    "resultUrl": null,
    "error": null,
    "createdAt": "2024-11-02T09:00:00.000Z",
    "updatedAt": "2024-11-02T09:22:17.000Z",
    "completedAt": "2024-11-02T09:22:17.000Z",
    "expiresAt": "2024-11-09T09:00:00.000Z"
  }
}

Cancellation only applies to non-terminal jobs. Calling this endpoint on a job that is already completed, completed_with_errors, failed, cancelled, or expired will return an error. Additionally, any pages that Plangrep had already processed at the time of cancellation may still be billed — cancellation does not reverse charges for work already performed.

​Authentication

​Endpoint

​Path Parameters

​Request Body

​Example Request

​Response Fields

​Example Response

Authentication

Endpoint

Path Parameters

Request Body

Example Request

Response Fields

Example Response