Skip to main content
After completing uploads, Plangrep processes your files asynchronously. You can track progress by polling the job state endpoint or by receiving push notifications via a webhook URL you configure when creating the job.

​
Polling

Call GET /api/open/v1/jobs/{jobId} at a regular interval and inspect the job.status field in the response: 
curl https://plangrep.com/api/open/v1/jobs/job_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Job status reference

StatusTerminal?Description
provisioningNoProject runtime is starting up
awaiting_uploadsNoJob created; waiting for file uploads
uploadingNoFiles are being received
preflightingNoValidating files and checking credits
blocked_insufficient_creditsNoProcessing paused; add credits to resume
processingNoActive processing underway
completedYesAll files processed successfully
completed_with_errorsYesProcessing finished with non-fatal errors
failedYesProcessing failed; check errors in the result
cancelledYesJob was cancelled by request
expiredYesJob expired before processing completed
Stop polling when you reach any terminal status. Continue polling for all non-terminal statuses.
Poll no faster than every 5 seconds. A recommended interval is every 10–30 seconds to stay well within rate limits.

​
Polling loop example

import time
import requests

def poll_job(job_id, api_key, timeout=600):
    terminal = {"completed", "completed_with_errors", "failed", "cancelled", "expired"}
    url = f"https://plangrep.com/api/open/v1/jobs/{job_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    start = time.time()

    while time.time() - start < timeout:
        resp = requests.get(url, headers=headers).json()
        status = resp["job"]["status"]
        print(f"Job status: {status}")
        if status in terminal:
            return resp["job"]
        time.sleep(15)

    raise TimeoutError("Job did not complete in time")

​
Webhooks

Register a webhook URL at job creation time to receive push notifications instead of polling: 
{
  "webhookUrl": "https://myapp.example.com/webhooks/plangrep"
}
Plangrep sends an HTTP POST request to your URL whenever the job status changes. Use the webhookSigningSecret returned at job creation time to verify that each request originated from Plangrep before processing it.
Your webhook endpoint must respond with a 2xx status code within a reasonable timeout. Failed deliveries may not be retried — use polling as a fallback for critical workflows.

​
Handling blocked jobs

If a job enters blocked_insufficient_credits, processing is paused until you add credits to your account. Once credits are available, resume the job: 
curl -X POST https://plangrep.com/api/open/v1/jobs/job_xyz789/resume \
  -H "Authorization: Bearer YOUR_API_KEY"
The job will re-enter preflighting and then processing after a successful resume.

​
Cancelling a job

To cancel a job that is still in progress, send a cancellation request: 
curl -X POST https://plangrep.com/api/open/v1/jobs/job_xyz789/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"
Only jobs in a non-terminal status can be cancelled. The response contains the updated job object with status set to "cancelled".
Cancellation may not be immediate if processing is already underway. Poll the job status to confirm the transition to "cancelled".