Show a direct-VM runner's capacity and cache disks

GET/api/workspaces/{workspace_id}/runners/{runner_id}/vm-cache

getWorkspaceRunnerVmCache

The runner's last capacity report and the cache disks of its host the server learnt of from completions (ADR 0146), most recently used first. Asks the workspace runner list's own permission first, then shows the runner to whoever sees it in that list; each disk is listed only if the caller may read its repository, and the totals count only the listed disks. 404 for a runner the caller cannot see.

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

curl

curl -X GET 'https://neosource.dev/api/workspaces/WORKSPACE_ID/runners/RUNNER_ID/vm-cache' \
  -H 'Authorization: Bearer $NEOSOURCE_TOKEN'

fetch

fetch("https://neosource.dev/api/workspaces/WORKSPACE_ID/runners/RUNNER_ID/vm-cache", {
  method: "GET",
  headers: {
    Authorization: "Bearer $NEOSOURCE_TOKEN",
  },
});

Path parameters

workspace_idrequired: string
runner_idrequired: string

Responses

200Capacity and cache disks

application/json

RunnerVmCacheResponse

object

A direct-VM runner's capacity and cache inventory (ADR 0146).

capacity

one of

RunnerVmCapacityResponse
object
A direct-VM runner's last capacity report (ADR 0146).
free_memory_mibrequired
integerint32
free_vcpusrequired
integerint32
memory_budget_mibrequired
integerint32
reported_atrequired
integerint64
When the runner reported it (Unix millis).
vcpu_budgetrequired
integerint32
null

disksrequired

array

items

RunnerVmCacheDiskResponse

object

One cache disk of a direct-VM runner, as the server last learnt it from a job's completion.

cache_keyrequired: string
generationrequired: integerint64
How many times a job committed this disk.
job_keyrequired: string
last_committed_at: integer | nullint64
last_used_atrequired: integerint64
matrix_values: object | null
The matrix leg's values, or `null` for a job without a matrix.
repo_idrequired: string
repositoryrequired: string
`owner/name`; empty if the repository is gone.
runsrequired: integerint64
staterequired: VmCacheDiskState
warm_runsrequired: integerint64
workflow_idrequired: string

runner_idrequired

string

totalsrequired

RunnerVmCacheTotalsResponse

object

Totals over the cache disks in the same response.

committedrequired: integerint64
Disks currently committed.
runsrequired: integerint64
Jobs that ran on these disks' keys, and how many of them forked warm.
warm_runsrequired: integerint64

403Forbidden — one of: forbidden, needs_scope

application/json

one of

ErrorForbidden
NeedsScopeError
object
`403` body returned when a classic OAuth token is asked for something its granted scopes do not cover — an explicit private listing without `repo`, or the one-click GitHub mirror without `admin:public_key`. `scope` names the missing grant so the client can say exactly what the token lacks. There is no elevation route to widen it any more (a re-link goes through the GitHub App, whose tokens carry no scopes), so the client's answer is to say so, never to start a handshake.
errorrequired
string
Always `needs_scope` — this body exists to carry the extra fields that kind needs.
"needs_scope"
scoperequired
string
The provider scope to request via elevation (e.g. `"repo"`).

Standard errors

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

400Bad Request — one of: invalid_input
401Authentication required
404Not Found — one of: not_found
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.

`VmCacheDiskState`

string

Whether a runner holds a committed cache disk for a key, as the server last learnt it from a completion.

"committed""absent"