Job API¶

The Job API exposes submitted work independently of which project URL created it. Use a user API credential. Ordinary users can access their own jobs and jobs without an owner; administrators have broader access. An inaccessible ID can return 404 rather than disclose another user's job.

Paths are relative to the API base URL. Project-scoped job paths expose the same individual-job operations; see Project API. A worker's execution state is reported through the Launcher API, not the user annotation endpoints.

Operations¶

job_id is the string returned as jobID at submission. Retrying and dismissing change server state; they are not monitoring operations.

List parameters¶

Optional parameters are omitted by default. For repeated parameters, send one query entry per value, not a comma-separated list. Each order_by value is an object with column, direction (ASC or DESC), and order (precedence):

{"column": "created", "direction": "DESC", "order": "1"}

Only use columns supported by the deployed endpoint. A limit is not a cursor or offset: do not assume Kubernetes-style watch/continue behavior or pagination parameters that AntFlow does not expose. The project job list has a different filter set and uses process_id instead of process_id_list.

StatusInfo¶

AntFlow adds fields such as project_path, project_ref, commit_ref, user_id, username, execution_content, assigned_to, comment, tags, and can_retry. They are extensions rather than mandatory OGC fields. Do not treat display-formatted assigned_to in user status responses as a canonical launcher ID. Use the Launcher API's id for launcher operations.

The five user-facing statuses are accepted, running, successful, failed, and dismissed. Internal worker states are mapped as follows:

A user-facing dismissed response can therefore mean cancellation is pending in the worker. Polling clients should handle terminal states and errors; an accepted response does not establish that execution has started.

JobList contains a required jobs array of StatusInfo and optional links. Follow resource links that are actually returned. Do not assume optional fields are present or expose response bodies containing sensitive workflow inputs in logs.

Results¶

The results response is an object keyed by result group, not a list of status objects or an execution request:

Groups depend on stored publication metadata and may be absent. A successful job with no available metadata returns 404 (ResultsNotReady). Unfinished or dismissed jobs also return 404 for results; a failed job returns 500 (JobResultsFailed). Presence of a results link does not guarantee a successful results response.

Follow returned URLs. The data API can proxy a file or redirect to a temporary S3 URL. See Results and publication for credential handling, downloads, and retention.

Logs¶

The logs operation streams the first stored log URL ending in stderr.log. It is not a live, combined log stream for every workflow container. Missing log metadata or an unavailable upstream file can cause the stream to fail after response streaming begins; check for transport errors and incomplete downloads rather than relying only on the initial HTTP status. Use logsOutput links for other published logs. Availability depends on the launcher and publication progress.

JobAnnotations¶

PUT and PATCH both accept a JSON annotation object and update only fields present in that object. They do not replace the job or change its worker state.

{"comment": "Validated calculator run", "tags": ["verified"]}

An empty object makes no annotation changes. Omit fields to leave them unchanged; send null to clear a nullable annotation. A permitted update returns the job's StatusInfo. This request is distinct from a launcher worker's Job body.

Retry¶

A retry requires a failed job still within the instance's retry window. Otherwise the server returns 400. Inspect can_retry when provided, but expect the server to recheck eligibility when you submit the request.

Retry keeps the job ID and inputs, resets it to accepted, and clears start/finish timestamps. An assigned job targets its previous launcher again. It is not a new submission with different inputs and can consume resources. See Job retries for policy.

Dismissal¶

DELETE requests cancellation; it does not erase the job record or delete published storage. An accepted unassigned job becomes dismissed immediately. Pending or running work is marked for worker dismissal. Already dismissed jobs are left dismissed; finalizing, successful, or failed jobs return 400. Execution infrastructure may take time to stop, and HPC jobs can require additional site-specific cleanup.

For a submission and monitoring procedure, follow Run a workflow through the API.