Overview
The API v3 endpoint GET /api/v3/jobs/{id}/resource-usage returns the CPU, memory, and network usage recorded for a job. Use it to check whether a job is sized correctly, for example to confirm that a job is hitting its memory limit before you move it to a larger resource class.
Before you begin
A personal API token. Send it as
Authorization: Bearer <token>.The job's UUID. V3 identifies jobs by UUID, not by job number.
A job that ran on CircleCI cloud with the Docker executor. API v3 is not available on CircleCI server.
Steps
Find the job ID. List the jobs in a workflow with
filter[workflow_id]:curl -g 'https://circleci.com/api/v3/jobs?filter[workflow_id]=<workflow-id>' \ --header "Authorization: Bearer $CIRCLE_TOKEN"
Read the
idof the job fromdata[].id. If you only have a project, see "Retrieve Build Data via the API" to walk from project to run to workflow to job.Request the resource usage for that job:
curl 'https://circleci.com/api/v3/jobs/<job-id>/resource-usage' \ --header "Authorization: Bearer $CIRCLE_TOKEN"
Example response
{ "data": {
"id": "<job-id>",
"attributes": {
"resource_class": {
"name": "medium",
"cpu_count": 2,
"memory_limit_bytes": 4294967296
},
"parallel_executions": [
{
"execution": 0,
"interval_ms": 1000,
"cpu_cores": [0.4, 1.8, 1.9],
"memory_bytes": [524288000, 1610612736, 2147483648],
"network_rx_bytes": 104857600,
"network_tx_bytes": 2097152
}
]
}
}
}Field | Meaning |
| The resource class the job ran on, with its |
| One entry per parallel execution, numbered from |
| Time between samples. |
| Ordered samples, one per interval. Samples carry no timestamps. The first sample is the first collection after the execution started. |
| Network bytes received and sent. |
To judge sizing, compare the highest memory_bytes and cpu_cores values with memory_limit_bytes and cpu_count. Memory close to the limit, or CPU pinned at cpu_count, suggests the job needs a larger resource class.
Limitations
Docker only. Machine and runner jobs return
200with an emptyparallel_executionslist.90-day retention. Recordings expire after 90 days.
Missing is not "did not run". An execution that recorded nothing is left out of the list instead of returned empty.
Errors
Branch on the HTTP status code, not on the message.
Code | Meaning |
| Invalid input, such as an |
| The token is missing or invalid. |
| Your token cannot access this job. |
| No job exists with that ID. A job number or slug is not a valid ID. See "CircleCI API v3 Returns 404 Not Found". |
| Rate limited. Wait the number of seconds in the |