--- title: List On-Call schedule overrides description: Retrieve a list of overrides for the specified On-Call schedule within a given time range. breadcrumbs: Documentation > API > List On-Call schedule overrides --- > For the complete documentation index, see [llms.txt](https://dnd37xeb23o8n.cloudfront.net/jen.gilbert/astro-base/llms.txt). # List On-Call schedule overrides {% callout %} This product or feature is not supported for the following sites: us2.ddog-gov.com {% /callout %} ## v2 (latest) | Datadog site | API endpoint | | ----------------- | ---------------------------------------------------------------------------------- | | app.datadoghq.com | GET https://api.datadoghq.com/api/v2/on-call/schedules/{schedule_id}/overrides | | us3.datadoghq.com | GET https://api.us3.datadoghq.com/api/v2/on-call/schedules/{schedule_id}/overrides | | us5.datadoghq.com | GET https://api.us5.datadoghq.com/api/v2/on-call/schedules/{schedule_id}/overrides | | app.datadoghq.eu | GET https://api.datadoghq.eu/api/v2/on-call/schedules/{schedule_id}/overrides | | ap1.datadoghq.com | GET https://api.ap1.datadoghq.com/api/v2/on-call/schedules/{schedule_id}/overrides | | ap2.datadoghq.com | GET https://api.ap2.datadoghq.com/api/v2/on-call/schedules/{schedule_id}/overrides | | uk1.datadoghq.com | GET https://api.uk1.datadoghq.com/api/v2/on-call/schedules/{schedule_id}/overrides | | app.ddog-gov.com | GET https://api.ddog-gov.com/api/v2/on-call/schedules/{schedule_id}/overrides | | us2.ddog-gov.com | GET https://api.us2.ddog-gov.com/api/v2/on-call/schedules/{schedule_id}/overrides | ### Overview Retrieve a list of overrides for the specified On-Call schedule within a given time range. This endpoint requires the `on_call_read` permission. ### Arguments #### Path Parameters | Field | Type | Description | | ------------------------ | ------ | ----------------------- | | schedule_id [*required*] | string | The ID of the schedule. | #### Query Strings | Field | Type | Description | | -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | filter[start] [*required*] | string | Start of the time range to retrieve overrides for, in RFC3339 format (for example, `2025-05-07T02:53:01Z` or `2025-05-07T02:53:01+00:00`). If you use a time zone offset with `+`, URL-encode the `+` as `%2B`. | | filter[end] [*required*] | string | End of the time range to retrieve overrides for, in RFC3339 format (for example, `2025-05-07T02:53:01Z` or `2025-05-07T02:53:01+00:00`). If you use a time zone offset with `+`, URL-encode the `+` as `%2B`. The time range cannot exceed 45 days. | | include | string | Comma-separated list of related resources to include in the response. Allowed values: `user`, `overridden_user`, `user.color`. | | page[size] | integer | Number of overrides to return per page. The maximum allowed value is 50. Default: `10`. | | page[number] | integer | Specific page number to return. Default: `0`. | ### Response {% tabs %} {% tab label="200" %} OK {% tabs %} {% tab label="Model" %} A list of on-call schedule overrides and any related included resources (such as users). | Parent field | Field | Type | Description | | --------------- | ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | | data [*required*] | [object] | A list of on-call schedule overrides. | | data | attributes | object | Attributes for an on-call schedule override. | | attributes | end | date-time | The end time of the override. | | attributes | inactive | boolean | Whether the override is inactive (for example, because its time range has ended). | | attributes | start | date-time | The start time of the override. | | data | id [*required*] | string | The unique identifier of the override. | | data | relationships | object | Relationships for an on-call schedule override. | | relationships | overridden_user | object | Defines the relationship between an override and one of its associated users. | | overridden_user | data [*required*] | object | A reference to a user, containing the user's ID and resource type. | | data | id [*required*] | string | The unique identifier of the user. | | data | type [*required*] | enum | Indicates that the related resource is of type 'users'. Allowed enum values: `users`. Default: `users`. | | relationships | schedule | object | Defines the relationship between an override and the schedule it belongs to. | | schedule | data [*required*] | object | A reference to the schedule the override belongs to, containing the schedule's ID and resource type. | | data | id [*required*] | string | The unique identifier of the schedule. | | data | type [*required*] | enum | Indicates that the related resource is of type 'schedules'. Allowed enum values: `schedules`. Default: `schedules`. | | relationships | user | object | Defines the relationship between an override and one of its associated users. | | user | data [*required*] | object | A reference to a user, containing the user's ID and resource type. | | data | id [*required*] | string | The unique identifier of the user. | | data | type [*required*] | enum | Indicates that the related resource is of type 'users'. Allowed enum values: `users`. Default: `users`. | | data | type [*required*] | enum | Indicates that the resource is of type 'overrides'. Allowed enum values: `overrides`. Default: `overrides`. | | | included | [] | Related resources referenced in the overrides' relationships, such as users. | | included | | object | Represents a user object in the context of a schedule, including their `id`, type, and basic attributes. | | | attributes | object | Provides basic user information for a schedule, including a name and email address. | | attributes | color | string | The user's on-call color, as a hex code (for example, `#FF0000`). Included only when `user.color` is requested in the `include` parameter. | | attributes | email | string | The user's email address. | | attributes | name | string | The user's name. | | attributes | status | enum | The user's status. Allowed enum values: `active`, `deactivated`, `pending`. | | | id [*required*] | string | The unique user identifier. | | | type [*required*] | enum | Users resource type. Allowed enum values: `users`. Default: `users`. | {% /tab %} {% tab label="Example" %} ```json { "data": [ { "attributes": { "end": "2024-01-08T02:53:01.000000000Z", "inactive": false, "start": "2024-01-07T02:53:01.000000000Z" }, "id": "00000000-0000-0000-0000-000000000000", "relationships": { "schedule": { "data": { "id": "3653d3c6-0c75-11ea-ad28-fb5701eabc7d", "type": "schedules" } }, "user": { "data": { "id": "00000000-aba1-0000-0000-000000000000", "type": "users" } } }, "type": "overrides" } ], "included": [ { "attributes": { "email": "jane.doe@example.com", "name": "Jane Doe", "status": "" }, "id": "00000000-aba1-0000-0000-000000000000", "type": "users" } ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="400" %} Bad Request {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="401" %} Unauthorized {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="403" %} Forbidden {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="404" %} Not Found {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="429" %} Too many requests {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% /tabs %} ### Code Example {% tabs %} {% tab label="Curl" %} ```bash # Path parameters export schedule_id="3653d3c6-0c75-11ea-ad28-fb5701eabc7d" # Required query arguments export filter_start="2024-01-07T02:53:01Z" export filter_end="2024-01-14T02:53:01Z" # Set your Datadog site and credentials export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com # Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" curl -X GET "https://api.${DD_SITE}/api/v2/on-call/schedules/${schedule_id}/overrides?filter%5Bstart%5D=${filter_start}&filter%5Bend%5D=${filter_end}" \ -H "Accept: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" ``` {% /tab %} {% /tabs %}