Retrieves the on-call responders for the specified schedule, grouped by position (previous, current, next), at a given time. Supports schedules with multiple concurrent on-call responders at a position, by returning a list of shifts per position.
This endpoint requires the on_call_read permission.
Arguments
Path Parameters
Name
Type
Description
schedule_id [required]
string
The ID of the schedule.
Query Strings
Name
Type
Description
include
string
Comma-separated list of included relationships to be returned. Allowed values: schedule, responders, responders.shifts, responders.shifts.user.
filter[position]
string
Comma-separated list of positions to retrieve. Allowed values: previous, current, next. Defaults to current if omitted.
filter[at_ts]
string
Retrieves the on-call responders at the given timestamp in RFC3339 format (for example, 2025-05-07T02:53:01Z or 2025-05-07T02:53:01+00:00). When using timezone offsets with + or -, ensure proper URL encoding (+ should be encoded as %2B). Defaults to the current time if omitted.
Root object representing a schedule’s on-call responders, grouped by position (previous, current, next), for a given point in time.
Expand All
Field
Type
Description
data
object
The main data object representing a schedule's on-call responders lookup, including relationships and metadata.
attributes
object
Attributes for a schedule's on-call responders lookup.
scheduled_at
date-time
The timestamp the responders were resolved at.
id
string
Unique identifier of this on-call responders lookup.
relationships
object
Relationships for a schedule's on-call responders lookup, including the schedule and its responder groups.
responders
object
Defines the list of per-position (previous, current, next) responder groups for the schedule.
data
[object]
Array of references to the responder groups included in the response.
id [required]
string
Unique identifier of the responder group.
type [required]
enum
Identifies the resource type for a responder group linked to a schedule's on-call responders lookup.
Allowed enum values: schedule_oncall_responder
default: schedule_oncall_responder
schedule
object
Defines the relationship to the schedule this on-call responders lookup was performed for.
data
object
Represents a reference to the schedule this on-call responders lookup was performed for.
id [required]
string
Unique identifier of the schedule.
type [required]
enum
Identifies the resource type for the schedule associated with this on-call responders lookup.
Allowed enum values: schedules
default: schedules
type [required]
enum
Represents the resource type for a schedule's grouped on-call responders across the previous, current, and next positions.
Allowed enum values: schedule_oncall_responders
default: schedule_oncall_responders
included
[ <oneOf>]
Related resources referenced in the responder groups' relationships, such as shifts, schedules, and users.
<type=schedule_oncall_responder>
object
Represents one position's (previous, current, or next) group of on-call responder shifts. Positions with no matching shift are omitted entirely from the response.
attributes
object
Attributes for one position's (previous, current, or next) group of on-call responder shifts.
position
enum
Specifies the position of a schedule target (example previous, current, or next).
Allowed enum values: previous,current,next
id
string
Unique identifier of this responder group.
relationships
object
Relationships for a single position's (previous, current, or next) responder group.
shifts
object
Defines the list of shifts satisfying this responder group's position. Multiple shifts occur when a schedule has multiple concurrent on-call responders at that position.
data
[object]
Array of references to the shifts included in the response.
id [required]
string
Unique identifier of the shift.
type [required]
enum
Indicates that the related resource is of type shifts.
Allowed enum values: shifts
default: shifts
type [required]
enum
Represents the resource type for a single position's (previous, current, or next) group of on-call responder shifts.
Allowed enum values: schedule_oncall_responder
default: schedule_oncall_responder
<type=shifts>
object
Data for an on-call shift.
attributes
object
Attributes for an on-call shift.
end
date-time
The end time of the shift.
start
date-time
The start time of the shift.
id
string
The ShiftDataid.
relationships
object
Relationships for an on-call shift.
user
object
Defines the relationship between a shift and the user who is working that shift.
data [required]
object
Represents a reference to the user assigned to this shift, containing the user's ID and resource type.
id [required]
string
Specifies the unique identifier of the user.
type [required]
enum
Indicates that the related resource is of type 'users'.
Allowed enum values: users
default: users
type [required]
enum
Indicates that the resource is of type 'shifts'.
Allowed enum values: shifts
default: shifts
<type=schedules>
object
Represents the primary data object for a schedule, linking attributes and relationships.
attributes
object
Provides core properties of a schedule object such as its name and time zone.
name
string
A short name for the schedule.
tags
[string]
A list of tags associated with the schedule.
time_zone
string
The time zone in which this schedule operates.
id
string
The schedule's unique identifier.
relationships
object
Groups the relationships for a schedule object, referencing layers and teams.
layers
object
Associates layers with this schedule in a data structure.
data
[object]
An array of layer references for this schedule.
id [required]
string
The unique identifier of the layer in this relationship.
type [required]
enum
Layers resource type.
Allowed enum values: layers
default: layers
teams
object
Associates teams with this schedule in a data structure.
data
[object]
An array of team references for this schedule.
id [required]
string
The unique identifier of the team in this relationship.
"""
Get on-call responders for a schedule returns "OK" response
"""fromosimportenvironfromdatadog_api_clientimportApiClient,Configurationfromdatadog_api_client.v2.api.on_call_apiimportOnCallApi# there is a valid "schedule" in the systemSCHEDULE_DATA_ID=environ["SCHEDULE_DATA_ID"]configuration=Configuration()withApiClient(configuration)asapi_client:api_instance=OnCallApi(api_client)response=api_instance.get_schedule_on_call_responders(schedule_id=SCHEDULE_DATA_ID,)print(response)
# Get on-call responders for a schedule returns "OK" responserequire"datadog_api_client"api_instance=DatadogAPIClient::V2::OnCallAPI.new# there is a valid "schedule" in the systemSCHEDULE_DATA_ID=ENV["SCHEDULE_DATA_ID"]papi_instance.get_schedule_on_call_responders(SCHEDULE_DATA_ID)
// Get on-call responders for a schedule returns "OK" responsepackagemainimport("context""encoding/json""fmt""os""github.com/DataDog/datadog-api-client-go/v2/api/datadog""github.com/DataDog/datadog-api-client-go/v2/api/datadogV2")funcmain(){// there is a valid "schedule" in the systemScheduleDataID:=os.Getenv("SCHEDULE_DATA_ID")ctx:=datadog.NewDefaultContext(context.Background())configuration:=datadog.NewConfiguration()apiClient:=datadog.NewAPIClient(configuration)api:=datadogV2.NewOnCallApi(apiClient)resp,r,err:=api.GetScheduleOnCallResponders(ctx,ScheduleDataID,*datadogV2.NewGetScheduleOnCallRespondersOptionalParameters())iferr!=nil{fmt.Fprintf(os.Stderr,"Error when calling `OnCallApi.GetScheduleOnCallResponders`: %v\n",err)fmt.Fprintf(os.Stderr,"Full HTTP response: %v\n",r)}responseContent,_:=json.MarshalIndent(resp,""," ")fmt.Fprintf(os.Stdout,"Response from `OnCallApi.GetScheduleOnCallResponders`:\n%s\n",responseContent)}
// Get on-call responders for a schedule returns "OK" responseimportcom.datadog.api.client.ApiClient;importcom.datadog.api.client.ApiException;importcom.datadog.api.client.v2.api.OnCallApi;importcom.datadog.api.client.v2.model.ScheduleOnCallResponders;publicclassExample{publicstaticvoidmain(String[]args){ApiClientdefaultClient=ApiClient.getDefaultApiClient();OnCallApiapiInstance=newOnCallApi(defaultClient);// there is a valid "schedule" in the systemStringSCHEDULE_DATA_ID=System.getenv("SCHEDULE_DATA_ID");try{ScheduleOnCallRespondersresult=apiInstance.getScheduleOnCallResponders(SCHEDULE_DATA_ID);System.out.println(result);}catch(ApiExceptione){System.err.println("Exception when calling OnCallApi#getScheduleOnCallResponders");System.err.println("Status code: "+e.getCode());System.err.println("Reason: "+e.getResponseBody());System.err.println("Response headers: "+e.getResponseHeaders());e.printStackTrace();}}}
// Get on-call responders for a schedule returns "OK" response
usedatadog_api_client::datadog;usedatadog_api_client::datadogV2::api_on_call::GetScheduleOnCallRespondersOptionalParams;usedatadog_api_client::datadogV2::api_on_call::OnCallAPI;#[tokio::main]asyncfnmain(){// there is a valid "schedule" in the system
letschedule_data_id=std::env::var("SCHEDULE_DATA_ID").unwrap();letconfiguration=datadog::Configuration::new();letapi=OnCallAPI::with_config(configuration);letresp=api.get_schedule_on_call_responders(schedule_data_id.clone(),GetScheduleOnCallRespondersOptionalParams::default(),).await;ifletOk(value)=resp{println!("{:#?}",value);}else{println!("{:#?}",resp.unwrap_err());}}
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com"DD_API_KEY="<DD_API_KEY>"DD_APP_KEY="<DD_APP_KEY>"cargo run
/**
* Get on-call responders for a schedule returns "OK" response
*/import{client,v2}from"@datadog/datadog-api-client";constconfiguration=client.createConfiguration();constapiInstance=newv2.OnCallApi(configuration);// there is a valid "schedule" in the system
constSCHEDULE_DATA_ID=process.env.SCHEDULE_DATA_IDasstring;constparams: v2.OnCallApiGetScheduleOnCallRespondersRequest={scheduleId: SCHEDULE_DATA_ID,};apiInstance.getScheduleOnCallResponders(params).then((data: v2.ScheduleOnCallResponders)=>{console.log("API called successfully. Returned data: "+JSON.stringify(data));}).catch((error: any)=>console.error(error));