# On Calls

## GET /on-calls

> List on-calls with flexible filters

```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.3-r.4"},"tags":[{"name":"On-Calls"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user <a href='/api-docs/#section/Authentication'>more info</a>.","name":"Authorization","in":"header"}},"schemas":{"OnCall":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/User"},"escalationPolicy":{"$ref":"#/components/schemas/EscalationPolicy"},"schedule":{"$ref":"#/components/schemas/ScheduleRel"},"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"escalationLevel":{"type":"number"}}},"User":{"required":["email","firstName","lastName"],"type":"object","properties":{"id":{"type":"integer","format":"int64"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"timezone":{"$ref":"#/components/schemas/TimeZone"},"position":{"type":"string"},"department":{"type":"string"},"avatarUrl":{"type":"string","readOnly":true},"language":{"type":"string","enum":["de","en"]},"region":{"type":"string","enum":["DE","GB","CH","CN","IN","US","FR","ES","CA","IE"]},"role":{"$ref":"#/components/schemas/Role"},"shiftColor":{"type":"string","description":"Optional hex-color code for the user's shifts in schedules calendars"},"mutedUntil":{"type":"string","description":"Date in ISO-8601","format":"date-time"},"createdAt":{"type":"string","description":"Date in ISO-8601","format":"date-time"},"updatedAt":{"type":"string","description":"Date in ISO-8601","format":"date-time"}}},"TimeZone":{"type":"string","enum":["Europe/Berlin","America/New_York","America/Los_Angeles","Asia/Istanbul"]},"Role":{"type":"string","enum":["STAKEHOLDER","GUEST","RESPONDER","USER","ADMIN"]},"EscalationPolicy":{"required":["escalationRules","name"],"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"escalationRules":{"type":"array","items":{"$ref":"#/components/schemas/EscalationRule"}},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamRel"}},"repeating":{"type":"boolean","default":false},"frequency":{"maximum":9,"minimum":1,"type":"integer","format":"int32","default":1},"delayMin":{"maximum":15,"minimum":0,"type":"integer","format":"int32","default":0},"routingKey":{"type":"string","description":"optional"}}},"EscalationRule":{"required":["escalationTimeout"],"type":"object","properties":{"escalationTimeout":{"type":"integer"},"user":{"type":"object","properties":{"id":{"type":"number"}},"description":"This field (type: User) is deprecated, please use 'users' instead"},"schedule":{"type":"object","properties":{"id":{"type":"number"}},"description":"This field (type: Schedule) is deprecated, please use 'schedules' instead"},"team":{"type":"object","properties":{"id":{"type":"number"}},"description":"This field (type: Team) is deprecated, please use 'teams' instead"},"users":{"type":"array","items":{"$ref":"#/components/schemas/UserRel"}},"schedules":{"type":"array","items":{"$ref":"#/components/schemas/ScheduleRel"}},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamRel"}}}},"UserRel":{"required":["id"],"type":"object","properties":{"id":{"type":"integer","format":"int64"},"firstName":{"type":"string"},"lastName":{"type":"string"}}},"ScheduleRel":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"},"type":{"type":"string","enum":["STATIC","RECURRING"]}}},"TeamRel":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}}}},"paths":{"/on-calls":{"get":{"tags":["On-Calls"],"summary":"List on-calls with flexible filters","parameters":[{"name":"policies","in":"query","description":"escalation policy ids to filter on call duties for","schema":{"type":"number"}},{"name":"policy-levels","in":"query","description":"can be provided instead of 'policies', must be a serialised and urlencoded JSON object e.g. ?policy-levels=\"{ \"id\": 12, \"level\": 1 }\" where id is the policy id and level is the escalation level that should be included","schema":{"type":"string"}},{"name":"schedules","in":"query","description":"on call schedule ids to filter on call duties for","schema":{"type":"number"}},{"name":"users","in":"query","description":"user ids to filter on call duties for","schema":{"type":"number"}},{"name":"expand","in":"query","description":"include full entities for: policy, escalationPolicy or user","schema":{"type":"string"}},{"name":"from","in":"query","description":"date-time ISO-UTC e.g. 2021-05-25T21:24:56.771Z, start of the time range, may not exceed 3 months in total span, defaults to current time","schema":{"type":"string"}},{"name":"until","in":"query","description":"date-time ISO-UTC e.g. 2021-05-25T21:24:56.771Z, end of the time range, must be after 'from', defaults to current time","schema":{"type":"string"}},{"name":"timezone","in":"query","description":"Time zone in which the results will be rendered, defaults to UTC","schema":{"type":"string"}},{"name":"start-index","in":"query","description":"offset for the search results, defaults to 0","schema":{"type":"number"}},{"name":"max-results","in":"query","description":"limit for the search results, defaults to 50, may not exceed 250","schema":{"type":"number"}}],"responses":{"200":{"description":"returns a list of on-call objects for the searched window","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/OnCall"}}}}}}}}}}
```