> 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

> Returns SLURM jobs from the database. Supports filtering by \`job\_ids\` (comma-separated list)\
> and \`cluster\_id\`

```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":{"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":"Returns SLURM jobs from the database. Supports filtering by `job_ids` (comma-separated list)\nand `cluster_id`","operationId":"list","parameters":[{"description":"Comma-separated list of SLURM job ids to filter by","in":"query","name":"job_ids","required":false,"schema":{"type":["string","null"]}},{"description":"Cluster id (UUID) to filter by","in":"query","name":"cluster_id","required":false,"schema":{"type":["string","null"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/SlurmJob"},"type":"array"}}},"description":"Returns jobs"},"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

```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"}},"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","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)"]}}}}
```

## List jobs (paginated)

> Returns SLURM jobs from the database with pagination

```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":{"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_paginated":{"get":{"description":"Returns SLURM jobs from the database with pagination","operationId":"list_paginated","parameters":[{"description":"Number of records to skip (default: 0)","in":"query","name":"offset","required":false,"schema":{"format":"int64","type":"integer"}},{"description":"Maximum number of records to return (default: 50, max: 100)","in":"query","name":"limit","required":false,"schema":{"format":"int64","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/SlurmJob"},"type":"array"}}},"description":"Returns jobs"},"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 (paginated)","tags":["Jobs (Slurm)"]}}}}
```