Jobs and plans

Starting a nest or a load answers 202 with a job. The job is where the search stands; the plan is what it made. Both are read by id, and both reads are free calls.

Check a job

curl https://api.nestsolver.com/v1/jobs/0192f0c4-7d1e-7c3a-9b2e-5d6f7a8b9c0d -H "Authorization: Bearer $NESTSOLVER_KEY"

The answer:

{
  "id": "0192f0c4-7d1e-7c3a-9b2e-5d6f7a8b9c0d",
  "kind": "nest",
  "status": "running",
  "lane": "full_speed",
  "search_seconds": 0,
  "plan_id": null,
  "failure": null,
  "links": { "status": "https://api.nestsolver.com/v1/jobs/0192f0c4-7d1e-7c3a-9b2e-5d6f7a8b9c0d", "plan": null }
}

status	Meaning
queued	Waiting for a slot. The workspace's "solves at once" and the lane decide how soon.
running	Searching, for up to the tier's longest search.
done	Finished. plan_id and links.plan point at the plan.
failed	Could not finish. failure says why, in the web's words; a strict job with a part that did not fit ends here.

search_seconds is how long the search ran, written when the job ends: it reads 0 while the job is queued or running. links.status and links.plan are full URLs.

lane is where the search runs: full_speed within the month's pool, slower past it, or deep on the Works plan once the pool is spent and the job asked for it. Plans and limits explains the lanes.

Polling

A nest or load searches for its tier's search time, from 15 seconds for a load on Free and a minute on the Bench plan to ten on the Works plan. Poll every few seconds; checks are free calls, so a poll every two seconds for ten minutes is well inside a paid tier's budget. Stop when status is done or failed.

A job id another workspace made, or none, answers 404.

Read a plan

curl https://api.nestsolver.com/v1/plans/0192f0c9-1a2b-7c3d-8e4f-5a6b7c8d9e0f -H "Authorization: Bearer $NESTSOLVER_KEY"

The answer:

{
  "id": "0192f0c9-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
  "kind": "nest",
  "created_at": "2026-03-14T09:12:44Z",
  "report": { "…": "the nest's report, or the load's" },
  "exports": {
    "dxf": "https://api.nestsolver.com/v1/plans/0192f0c9-1a2b-7c3d-8e4f-5a6b7c8d9e0f/exports/dxf",
    "svg": "https://api.nestsolver.com/v1/plans/0192f0c9-1a2b-7c3d-8e4f-5a6b7c8d9e0f/exports/svg",
    "labels": "https://api.nestsolver.com/v1/plans/0192f0c9-1a2b-7c3d-8e4f-5a6b7c8d9e0f/exports/labels",
    "packet": "https://api.nestsolver.com/v1/plans/0192f0c9-1a2b-7c3d-8e4f-5a6b7c8d9e0f/exports/packet"
  }
}

report is a NestReport for a nest and a LoadReport for a load; true-shape nesting and load planning describe them, and the API reference has every field. exports lists each file the plan offers, by format, with its URL. Exports explains them.

A plan the key's workspace did not make, or a nest or load its tier no longer includes, answers 404.

Plans on the web

The same plans are on the portal, in the workspace the key belongs to. A job started over the API shows up there with its report and exports, so a planner can check it before anything is cut.