> ## Documentation Index > Fetch the complete documentation index at: https://docs.halfpagetechnologies.com/llms.txt > Use this file to discover all available pages before exploring further. # Get job status > Poll a job's status after submitting a prediction or training job. Keep polling until `status` is `COMPLETED` (or `FAILED`). For a completed prediction the response carries the `segmentation_id` of the produced segmentation — feed that into the `/export/*` and `/segmentation/*` endpoints. A non-UUID `job_id` is rejected with `422` before it reaches the database. ## OpenAPI ````yaml /api-reference/openapi.json get /api/v1/job/{job_id} openapi: 3.1.0 info: title: HalfPage API description: > The **HalfPage API** runs Cellpose-based cell segmentation on your microscopy images programmatically — upload an image, run a prediction, and export the resulting cell masks, ROIs, and measurements. ## Base URL ``` https://api.halfpagetechnologies.com/backend/api/v1 ``` Every path in this reference is relative to that base URL. A staging environment is available at `https://staging-api.halfpagetechnologies.com/backend/api/v1`. ## Authentication Authenticate every request with an API key in the `Authorization` header as a bearer token: ``` Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxx ``` Create and manage keys from the **API Keys** section of the HalfPage dashboard — keys cannot be minted through the API. A key is scoped to the organization that owns it; every resource you create or read is confined to that organization. Requests without a valid key receive `401`; a valid key used against an endpoint outside the public product surface receives `403`. ## Core workflow Segmentation runs asynchronously on GPU workers, so the API is poll-based: 1. **Upload an image** (`POST /upload`) as `multipart/form-data` with a `file` field. One call: the image record is created automatically and the response returns it already `ready`, with the `image_id` for the next step. *(Large files: `POST /image` with `resumable: true` returns presigned part URLs — PUT the chunks, call `POST /upload/{image_id}/complete`, then poll `GET /image/{image_id}` until `upload_status` is `ready`.)* 2. **Pick a model** (`GET /models`) and **submit a prediction** (`POST /job/prediction`) with the `image_id` and a `model_id`. This returns a `job_id`. 3. **Poll the job** (`GET /job/{job_id}`) until `status` is `COMPLETED`; the response then carries a `segmentation_id`. 4. **Export** results for that segmentation as CSV measurements (`GET /export/{segmentation_id}/measurements.csv`), GeoJSON ROIs (`.../rois.geojson`), or an ImageJ ROI archive (`.../rois.zip`). To collect a whole project at once, `GET /export/project/{folder_id}/measurements.csv` returns every analyzed image in it as one CSV. ## Quotas Uploads and analyses are metered against your plan. Exceeding your image storage cap or monthly analysis cap returns `402` with a human-readable `detail` explaining the limit — upgrade your plan to raise it. version: 1.0.0 servers: - url: https://api.halfpagetechnologies.com/backend description: Production - url: https://staging-api.halfpagetechnologies.com/backend description: Staging security: [] tags: - name: upload description: >- Get microscopy images into HalfPage. The single-request `POST /upload` is the simplest path: it creates the image record for you and returns it `ready`. For large files over flaky connections, use the resumable flow: `POST /image` with `resumable: true` (or `init`), PUT the presigned parts, then `complete` (no ETag bookkeeping needed) and poll the image until `ready`. - name: job description: >- Submit and poll asynchronous GPU jobs. `POST /job/prediction` runs segmentation on a ready image; `POST /job/training` fine-tunes a custom model. Both return a `job_id` you poll via `GET /job/{job_id}` until it is `COMPLETED`. - name: image description: >- Create and manage image records. `POST /image` starts the resumable upload flow (with `resumable: true` it returns presigned part URLs in the same call); poll `GET /image/{image_id}` for the upload lifecycle (`uploading` → `processing` → `ready`) and metadata such as pixel `shape`, and delete images you no longer need. - name: segmentation description: >- Read the segmentations produced by prediction jobs and derive new ones. A segmentation is the set of detected cell ROIs for an image; fetch its metadata, regenerate its mask from annotations, or fork a refinement to iterate on the result. - name: export description: >- Download results in analysis-ready formats: a CSV of per-cell measurements, a GeoJSON of ROI polygons, or a ZIP of ImageJ-compatible ROIs. Export one segmentation at a time, or pull every analyzed image in a project into a single CSV. Both CSV endpoints accept a `columns` parameter to narrow the output to the measurements you care about. - name: models description: >- List the segmentation models available to your organization — the shared public base models (e.g. `cpsam`) plus any custom models you have trained — to choose a `model_id` for a prediction job. paths: /api/v1/job/{job_id}: get: tags: - job summary: Get job status description: >- Poll a job's status after submitting a prediction or training job. Keep polling until `status` is `COMPLETED` (or `FAILED`). For a completed prediction the response carries the `segmentation_id` of the produced segmentation — feed that into the `/export/*` and `/segmentation/*` endpoints. A non-UUID `job_id` is rejected with `422` before it reaches the database. operationId: get_job_api_v1_job__job_id__get parameters: - name: job_id in: path required: true schema: type: string format: uuid title: Job Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/JobStatusResponse' examples: running: summary: Still running (poll again) value: id: b1e5c7d2-9a4f-4c3b-8e2d-1f6a7b8c9d0e status: STARTED job_type: prediction image_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 model_id: c0ffee00-1234-5678-9abc-def012345678 pipeline_id: a2b3c4d5-6e7f-4a5b-8c9d-0e1f2a3b4c5d created_at: '2026-07-01T12:00:00Z' completed: summary: Completed — segmentation_id available value: id: b1e5c7d2-9a4f-4c3b-8e2d-1f6a7b8c9d0e status: COMPLETED job_type: prediction image_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 model_id: c0ffee00-1234-5678-9abc-def012345678 pipeline_id: a2b3c4d5-6e7f-4a5b-8c9d-0e1f2a3b4c5d created_at: '2026-07-01T12:00:00Z' segmentation_id: 7d9e2f10-4a5b-4c6d-8e9f-0a1b2c3d4e5f '401': description: >- Missing or invalid credentials. Supply a valid `Authorization: Bearer hp_live_...` API key. content: application/json: example: detail: Requires authentication schema: $ref: '#/components/schemas/ErrorResponse' '404': description: The resource does not exist, or is not in your organization. content: application/json: example: detail: Image with id 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- The path id is not a valid UUID (rejected before it reaches the database). content: application/json: example: detail: Input should be a valid UUID schema: $ref: '#/components/schemas/ErrorResponse' security: - HTTPBearer: [] components: schemas: JobStatusResponse: properties: id: type: string title: Id status: $ref: '#/components/schemas/JobStatus' job_type: $ref: '#/components/schemas/JobType' image_id: type: string title: Image Id model_id: type: string title: Model Id pipeline_id: anyOf: - type: string - type: 'null' title: Pipeline Id parent_job_id: anyOf: - type: string - type: 'null' title: Parent Job Id created_at: type: string format: date-time title: Created At segmentation_id: anyOf: - type: string - type: 'null' title: Segmentation Id type: object required: - id - status - job_type - image_id - model_id - created_at title: JobStatusResponse description: >- A job's polling snapshot: status plus the identifiers a caller needs to fetch its result. `segmentation_id` is populated only once the (prediction) job is COMPLETED and its segmentation exists. examples: - created_at: '2026-07-01T12:00:00Z' id: b1e5c7d2-9a4f-4c3b-8e2d-1f6a7b8c9d0e image_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6 job_type: prediction model_id: c0ffee00-1234-5678-9abc-def012345678 pipeline_id: a2b3c4d5-6e7f-4a5b-8c9d-0e1f2a3b4c5d segmentation_id: 7d9e2f10-4a5b-4c6d-8e9f-0a1b2c3d4e5f status: COMPLETED ErrorResponse: properties: detail: type: string title: Detail examples: - Job with id 11111111-1111-1111-1111-111111111111 not found type: object required: - detail title: ErrorResponse description: |- The body returned for a handled error: a single human-readable ``detail`` string. JobStatus: type: string enum: - SUBMITTED - STARTED - COMPLETED - FAILED title: JobStatus JobType: type: string enum: - prediction - training title: JobType securitySchemes: HTTPBearer: type: http scheme: bearer ````