> Documentation index for AI agents: https://docs.pagerduty.com/llms.txt

# List all of the on-calls

`GET https://api.pagerduty.com/oncalls`

List the on-call entries during a given time range.

An on-call represents a contiguous unit of time for which a User will be on call for a given Escalation Policy and Escalation Rules.

For more information see the [API Concepts Document](https://docs.pagerduty.com/developer/api-concepts#on-calls)

Scoped OAuth requires: `oncalls.read`

This API operation has operation specific rate limits. See the [Rate Limits](https://developer.pagerduty.com/docs/72d3b724589e3-rest-api-rate-limits) page for more information.

## Authorization

- **api_key** (apiKey) — `Authorization` header. The API Key with format `Token token=<API_KEY>`

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `time_zone` | string (tzinfo) |  | Time zone in which results will be rendered. This will default to the account time zone. |
| `limit` | integer |  | The number of results per page. |
| `offset` | integer |  | Offset to start pagination search results. |
| `total` | boolean |  | By default the `total` field in pagination responses is set to `null` to provide the fastest possible response times. Set `total` to `true` for this field to be populated. See our [Pagination Docs](https://docs.pagerduty.com/developer/pagination) for more information. Default: `false`. |
| `include[]` | string |  | Array of additional details to include. One of: `escalation_policies`, `users`, `schedules`. Items must be unique. |
| `user_ids[]` | array of string |  | Filters the results, showing only on-calls for the specified user IDs. Items must be unique. |
| `escalation_policy_ids[]` | array of string |  | Filters the results, showing only on-calls for the specified escalation policy IDs. Items must be unique. |
| `schedule_ids[]` | array of string |  | Filters the results, showing only on-calls for the specified schedule IDs. If `null` is provided in the array, it includes permanent on-calls due to direct user escalation targets. Items must be unique. |
| `since` | string (date-time) |  | The start of the time range over which you want to search. If an on-call period overlaps with the range, it will be included in the result. Defaults to current time. On-call shifts are limited to 90 days in the future. |
| `until` | string (date-time) |  | The end of the time range over which you want to search. If an on-call period overlaps with the range, it will be included in the result. Defaults to current time. On-call shifts are limited to 90 days in the future, and the `until` time cannot be before the `since` time. |
| `earliest` | boolean |  | This will filter on-calls such that only the earliest on-call for each combination of escalation policy, escalation level, and user is returned. This is useful for determining when the "next" on-calls are for a given set of filters. |

## Header parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `Accept` | string | yes | The `Accept` header is used as a versioning header. Default: `application/vnd.pagerduty+json;version=2`. |

## Response 200

A paginated array of on-call objects.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `offset` | integer |  | Echoes offset pagination property. Read-only. |
| `limit` | integer |  | Echoes limit pagination property. Read-only. |
| `more` | boolean |  | Indicates if there are additional records to return. Read-only. |
| `total` | integer \| null |  | The total number of records matching the given query. Read-only. |
| `oncalls` | array of object | yes |  |
| `oncalls[].escalation_policy` | object |  |  |
| `oncalls[].escalation_policy.id` | string | yes | Read-only. |
| `oncalls[].escalation_policy.summary` | string \| null |  | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. |
| `oncalls[].escalation_policy.type` | string | yes | One of: `escalation_policy_reference`. |
| `oncalls[].escalation_policy.self` | string \| null (url) |  | the API show URL at which the object is accessible. Read-only. |
| `oncalls[].escalation_policy.html_url` | string \| null (url) |  | a URL at which the entity is uniquely displayed in the Web app. Read-only. |
| `oncalls[].user` | object |  |  |
| `oncalls[].user.id` | string | yes | Read-only. |
| `oncalls[].user.summary` | string \| null |  | A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. |
| `oncalls[].user.type` | string | yes | One of: `user_reference`. |
| `oncalls[].user.self` | string \| null (url) |  | the API show URL at which the object is accessible. Read-only. |
| `oncalls[].user.html_url` | string \| null (url) |  | a URL at which the entity is uniquely displayed in the Web app. Read-only. |
| `oncalls[].schedule` | one of: object \| object |  | The schedule from which this on-call originates. May be a legacy schedule reference or a v3 schedule reference. |
| `oncalls[].schedule.id` | string | yes | (option 1) Read-only. |
| `oncalls[].schedule.summary` | string \| null |  | (option 1) A short-form, server-generated string that provides succinct, important information about an object suitable for primary labeling of an entity in a client. In many cases, this will be identical to `name`, though it is not intended to be an identifier. Read-only. |
| `oncalls[].schedule.type` | string | yes | (option 1) One of: `schedule_reference`. |
| `oncalls[].schedule.self` | string \| null (url) |  | (option 1) the API show URL at which the object is accessible. Read-only. |
| `oncalls[].schedule.html_url` | string \| null (url) |  | (option 1) a URL at which the entity is uniquely displayed in the Web app. Read-only. |
| `oncalls[].schedule.id` | string | yes | (option 2) |
| `oncalls[].schedule.type` | string | yes | (option 2) One of: `schedule_v3_reference`. |
| `oncalls[].schedule.summary` | string | yes | (option 2) Schedule name. |
| `oncalls[].schedule.self` | string (uri) |  | (option 2) |
| `oncalls[].schedule.html_url` | string (uri) |  | (option 2) |
| `oncalls[].escalation_level` | integer |  | The escalation level for the on-call. Read-only. |
| `oncalls[].start` | string (date-time) |  | The start of the on-call. If `null`, the on-call is a permanent user on-call. Read-only. |
| `oncalls[].end` | string (date-time) |  | The end of the on-call. If `null`, the user does not go off-call. Read-only. |

Example: Response Example

```json
{
  "oncalls": [
    {
      "user": {
        "id": "PT23IWX",
        "type": "user_reference",
        "summary": "Tim Wright",
        "self": "https://api.pagerduty.com/users/PT23IWX",
        "html_url": "https://subdomain.pagerduty.com/users/PT23IWX"
      },
      "schedule": {
        "id": "PI7DH85",
        "type": "schedule_reference",
        "summary": "Daily Engineering Rotation",
        "self": "https://api.pagerduty.com/schedules/PI7DH85",
        "html_url": "https://subdomain.pagerduty.com/schedules/PI7DH85"
      },
      "escalation_policy": {
        "id": "PT20YPA",
        "type": "escalation_policy_reference",
        "summary": "Engineering Escalation Policy",
        "self": "https://api.pagerduty.com/escalation_policies/PT20YPA",
        "html_url": "https://subdomain.pagerduty.com/escalation_policies/PT20YPA"
      },
      "escalation_level": 2,
      "start": "2015-03-06T15:28:51-05:00",
      "end": "2015-03-07T15:28:51-05:00"
    }
  ],
  "limit": 25,
  "offset": 0,
  "more": false,
  "total": null
}
```

## Response 400

Caller provided invalid arguments. Please review the response for error details. Retrying with the same arguments will *not* work.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 401

Caller did not supply credentials or did not provide the correct credentials.
If you are using an API key, it may be invalid or your Authorization header may be malformed.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 403

Caller is not authorized to view the requested resource.
While your authentication is valid, the authenticated user or token does not have permission to perform this action.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Response 429

Too many requests have been made, the rate limit has been reached.

### `application/json`

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object |  |  |
| `error.code` | integer |  | Read-only. |
| `error.message` | string |  | Error message string. Read-only. |
| `error.errors` | array of string |  | Read-only. |

## Developer Agreement

Your access to and use of the PagerDuty Developer Services is governed by the [PagerDuty Developer Agreement](https://docs.pagerduty.com/developer/pagerduty-developer-agreement).