> For the complete documentation index, see [llms.txt](https://docs.cedana.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cedana.ai/references/api/jobs-slurm.md).

# Jobs (Slurm)

Cedana API for jobs (Slurm)

## List jobs

> Paginated. \`total\_count\` is the number of jobs matching the filters before paging.

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for jobs (Slurm)","name":"Jobs (Slurm)"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"PaginatedSlurmJobResponse":{"description":"One page of SLURM jobs plus the total number of jobs matching the query,\nso clients can compute page counts without walking every page.","properties":{"available_filters":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SlurmAvailableFilters"}]},"jobs":{"items":{"$ref":"#/components/schemas/SlurmJob"},"type":"array"},"total_count":{"format":"int64","type":"integer"}},"required":["jobs","total_count"],"type":"object"},"SlurmAvailableFilters":{"description":"Distinct filter values across all jobs (not just the current page)","properties":{"statuses":{"items":{"type":"string"},"type":"array"}},"required":["statuses"],"type":"object"},"SlurmJob":{"description":"SlurmJob represents a SLURM job stored in the database","properties":{"account":{"type":["string","null"]},"cluster_id":{"type":"string"},"derived_ec":{"description":"Numeric derived exit code (slurmdbd derived_ec — uint32, widened to i64)","format":"int64","type":["integer","null"]},"derived_es":{"description":"Human-readable exit reason (e.g. \"Preempted by higher-priority job\")","type":["string","null"]},"end_time":{"description":"Unix epoch seconds; 0 means not yet ended","format":"int64","type":["integer","null"]},"exit_code":{"format":"int64","type":["integer","null"]},"failed_node":{"description":"Node that triggered job failure, if any","type":["string","null"]},"id":{"format":"int64","type":"integer"},"job_id":{"format":"int64","type":"integer"},"kill_requid":{"description":"UID that issued the kill/preempt signal (uid_t / uint32, widened to i64)","format":"int64","type":["integer","null"]},"name":{"type":"string"},"nodes":{"type":"string"},"num_cpus":{"format":"int64","type":["integer","null"]},"num_nodes":{"format":"int64","type":["integer","null"]},"partition":{"type":["string","null"]},"priority":{"format":"int64","type":"integer"},"start_time":{"description":"Unix epoch seconds; 0 means not set","format":"int64","type":"integer"},"state_reason_prev":{"description":"Reason code for prior state transition","format":"int64","type":["integer","null"]},"status":{"type":"string"},"submit_time":{"description":"Unix epoch seconds; 0 means not set","format":"int64","type":"integer"},"time_suspended":{"description":"Seconds the job spent suspended","format":"int64","type":["integer","null"]},"work_dir":{"type":["string","null"]}},"type":"object"},"HttpError":{"description":"Standard JSON error body for all 4xx/5xx responses.\n\nHandlers return plain-text errors internally; [`normalize_error_response`]\nconverts anything the stack produces (handlers, extractors, the auth layer)\nto this shape, so generated SDK clients can rely on a single error schema.","properties":{"message":{"description":"Human-readable description of what went wrong","type":"string"}},"required":["message"],"type":"object"}}},"paths":{"/v1/slurm/jobs":{"get":{"description":"Paginated. `total_count` is the number of jobs matching the filters before paging.","operationId":"list","parameters":[{"description":"Exact SLURM job id to fetch; when set, all other filters are ignored","in":"query","name":"id","required":false,"schema":{"format":"int64","type":["integer","null"]}},{"description":"Row offset (default 0)","in":"query","name":"offset","required":false,"schema":{"format":"int64","type":["integer","null"]}},{"description":"Page size (default 50, max 500)","in":"query","name":"limit","required":false,"schema":{"format":"int64","type":["integer","null"]}},{"description":"One of: id, name, status, submit_time, start_time (default: start_time)","in":"query","name":"sort","required":false,"schema":{"type":["string","null"]}},{"description":"Sort ascending (default: false)","in":"query","name":"ascending","required":false,"schema":{"type":["boolean","null"]}},{"in":"query","name":"status","required":false,"schema":{"type":["string","null"]}},{"description":"Job name or job id to query against (uses postgres ILIKE pattern search)","in":"query","name":"job_name","required":false,"schema":{"type":["string","null"]}},{"description":"Only return jobs belonging to this cluster","in":"query","name":"cluster_id","required":false,"schema":{"format":"uuid","type":["string","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedSlurmJobResponse"}}},"description":"Returns jobs with total count and available filters"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Invalid query parameters"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to fetch from database"},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Client error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Server error"}},"summary":"List jobs","tags":["Jobs (Slurm)"]}}}}
```

## Sync jobs

> Receives a batch of SLURM jobs from the cedana-slurm plugin and upserts them into the database.\
> Unless the batch is partial, jobs on the cluster missing from it are marked completed.

```json
{"openapi":"3.1.0","info":{"title":"Cedana API","version":"0.0.0-dev"},"tags":[{"description":"Cedana API for jobs (Slurm)","name":"Jobs (Slurm)"}],"security":[{"Token":[]}],"components":{"securitySchemes":{"Token":{"scheme":"bearer","type":"http"}},"schemas":{"SlurmJobSyncRequest":{"description":"Sync request containing a batch of jobs","properties":{"cluster_id":{"format":"uuid","type":"string"},"jobs":{"description":"Raw SLURM records are retained because their schema varies by release.","items":{},"type":"array"},"partial":{"description":"The batch is only some of the cluster's jobs: upsert them, but don't\nmark the jobs missing from it as completed.","type":"boolean"}},"required":["cluster_id","jobs"],"type":"object"},"HttpError":{"description":"Standard JSON error body for all 4xx/5xx responses.\n\nHandlers return plain-text errors internally; [`normalize_error_response`]\nconverts anything the stack produces (handlers, extractors, the auth layer)\nto this shape, so generated SDK clients can rely on a single error schema.","properties":{"message":{"description":"Human-readable description of what went wrong","type":"string"}},"required":["message"],"type":"object"}}},"paths":{"/v1/slurm/jobs/sync":{"post":{"description":"Receives a batch of SLURM jobs from the cedana-slurm plugin and upserts them into the database.\nUnless the batch is partial, jobs on the cluster missing from it are marked completed.","operationId":"sync","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlurmJobSyncRequest"}}},"required":true},"responses":{"200":{"content":{"text/plain":{"schema":{"type":"string"}}},"description":"Jobs synced successfully"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Failed to sync jobs to database"},"4XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Client error"},"5XX":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HttpError"}}},"description":"Server error"}},"summary":"Sync jobs","tags":["Jobs (Slurm)"]}}}}
```