Skip to main content
Poll the status of an async job and retrieve results when complete. The agent decides when and how often to poll — the tool never blocks.

​
When to Use

  • Check the status of a running comparison or parse job
  • Retrieve the list of generated overlays after a comparison completes
  • Report progress to the user while a job is processing
  • Short-poll with wait_seconds to reduce round-trips

​
Parameters

ParameterTypeRequiredDescription
job_idstringyesJob ID returned by Compare or Parse
wait_secondsnumbernoShort-poll: wait up to this many seconds for a status change (max 15). Reduces round-trips for fast jobs.

​
Response

​
In Progress

{
  "id": "job_cmp_01",
  "status": "started",
  "progress": {
    "completed": 3,
    "total": 8
  }
}
FieldTypeDescription
idstringJob ID
statusstring"queued", "started", or "completed"
progress.completednumberNumber of sheet pairs processed so far
progress.totalnumberTotal sheet pairs to process

​
Completed

{
  "id": "job_cmp_01",
  "status": "completed",
  "progress": {
    "completed": 8,
    "total": 8
  },
  "result": {
    "overlays": [
      {
        "id": "ov_01",
        "block_a": {
          "type": "Plan",
          "sheet_number": "A-101",
          "drawing_name": "Arch Set Rev A"
        },
        "block_b": {
          "type": "Plan",
          "sheet_number": "A-101",
          "drawing_name": "Arch Set Rev B"
        },
        "score": 0.82,
        "uri": "storage://overlays/ov_01/composite.png"
      }
    ]
  }
}
The score indicates how similar the two blocks are (0.0 = completely different, 1.0 = identical). Lower scores mean more changes. After completion, use Query with entity: "block" and include: ["overlays", "changes"] on either block to get detailed change and clash descriptions.

​
Failed

{
  "id": "job_cmp_01",
  "status": "failed",
  "error": {
    "code": "job_failed",
    "message": "Comparison failed: no matching sheets found between drawings"
  }
}

​
Examples

​
Poll a running comparison

{
  "job_id": "job_cmp_01"
}
If the job is still running, the agent can report progress to the user: “3 of 8 sheet pairs processed. Checking again…”

​
Retrieve completed results

{
  "job_id": "job_cmp_01"
}
When status is "completed", the result.overlays array lists every matched block pair with its similarity score. The agent can sort by score to identify sheets with the most changes and drill into them first.
A good polling pattern: wait 2-3 seconds after triggering Compare, then poll. For large drawing sets, the agent can tell the user “Processing 12 sheet pairs, this may take a minute” and poll at longer intervals.
  • Compare - Trigger a comparison job
  • Parse - Trigger a parse job
  • Query - Fetch detailed changes, clashes, or extracted features after the job completes
  • ViewImage - View overlay images referenced in the results