Docs
Search docs

Finish a job and release its lease

POST/api/runners/leases/{lease_id}/complete

completeJob

Requires authentication using a bearer token — see tokens and scopes.

curl

curl -X POST 'https://neosource.dev/api/runners/leases/LEASE_ID/complete' \
  -H 'Authorization: Bearer $NEOSOURCE_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"status":"string"}'

fetch

fetch("https://neosource.dev/api/runners/leases/LEASE_ID/complete", {
  method: "POST",
  headers: {
    Authorization: "Bearer $NEOSOURCE_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"status":"string"}),
});

Path parameters

lease_idrequired

string

Request bodyrequired

application/json

CompleteJobRequest

object

compile_cache
one of

  • CompileCacheReportDto

    object

    What the job's compiler cache reported at job end, straight from its own accounting (`sccache --show-stats --stats-format=json`). Absent means "this job said nothing about a compile cache" — which is the majority of jobs, since most compile nothing. Never read it as a cold cache.

    compilationsrequired

    integerint64

    Compilations actually performed — the count `compile_ms` aggregates over, and therefore the divisor for the mean compile.

    compile_msrequired

    integerint64

    hitsrequired

    integerint64

    missesrequired

    integerint64

    read_hit_msrequired

    integerint64

    TOTAL ms across all hits / all compilations, not per-request means.

    requestsrequired

    integerint64

  • null

error_message

string | null

exit_code

integer | nullint32

infra_failure
one of

  • JobInfraFailureReason

    string

    Why a runner's `failed` report is the CI platform's fault rather than the workflow's (#738, ADR 0156). Rides `complete` beside `status: failed`; the server requeues such a job once before it lets the failure stand. Closed on purpose: only a direct-VM agent sets it, at the three places where the VM died without the guest reporting an outcome. A job's own timeout, a cancel and every outcome the guest did report are the workflow's, and are never one of these.

    "vm_no_outcome""vm_boot_failed""vm_oom_overhead"

  • null

outputs

object

The job's evaluated `outputs:` block (empty for failed jobs and workflows without `outputs:`). Persisted on the job row so a later claim of a dependent job carries `needs.<job>.outputs.*`.

additional properties

string

statusrequired

WorkflowRunJobStatus

string

Lifecycle of an individual job inside a run. Distinct from the run-level status because `needs:` ordering means some jobs are `Waiting` while others are `Running`. The serde `snake_case` strings are the wire vocabulary the API emits (pinned by the `enum_wire_consistency` tests).

"waiting""ready""running""cancelling""succeeded""failed""cancelled""skipped"

vm_cache
one of

  • VmCacheReportDto

    object

    A direct-VM job's cache outcome (ADR 0146).

    evicted

    array

    Committed disks evicted for this job, at most 256 (400 above that).

    itemsVmCacheEvictionDto
    fork_failed

    boolean

    The run is cold because forking the committed disk failed, not because there was none, so the server keeps the disk `committed`.

    keyrequired

    string

    The cache key the agent derived. The server derives its own; a mismatch is logged, never trusted.

    memory_peak_mib

    integer | nullint32

    The job cgroup's peak memory, in MiB.

    resultrequired
    VmCacheResult
    warmrequired

    boolean

    The job forked a committed disk rather than a fresh one.

  • null

Responses

204Completed

Standard errors

Bodies documented once for the whole API — see standard errors.

  • 400Bad Request — one of: invalid_input
  • 401Authentication required
  • 403Forbidden — one of: forbidden
  • 404Not Found — one of: not_found
  • 409Conflict — one of: conflict
  • 429Rate limited — retry after the `Retry-After` header
  • 500Internal server error
  • 503Service temporarily unavailable / at capacity — retry after the `Retry-After` header
  • 504Gateway timeout — the request exceeded the server's handling budget

Schemas

Referenced above. Listed here rather than expanded inline, so the same definition is not repeated at every level.

VmCacheEvictionDto

object

A committed cache disk a direct-VM agent evicted.

evicted_at

integer | nullint64

When the disk was gone, in epoch milliseconds by the agent's clock. The server ignores the eviction if the disk was committed after it; without it the eviction applies unconditionally.

keyrequired

string

`[A-Za-z0-9_-]{1,64}`, else 400.

repo_idrequired

string

VmCacheResult

string

What became of a job's cache disk fork at completion.

"committed""discarded""commit_failed"