For AI agents: A markdown version of this page is available at https://docs.datadoghq.com/api/latest/on-call/get-on-call-responders-for-a-schedule.md. A documentation index is available at /llms.txt.
This product is not supported for your selected Datadog site. ().

Get on-call responders for a schedule

GET https://api.ap1.datadoghq.com/api/v2/on-call/schedules/{schedule_id}/respondershttps://api.ap2.datadoghq.com/api/v2/on-call/schedules/{schedule_id}/respondershttps://api.datadoghq.eu/api/v2/on-call/schedules/{schedule_id}/respondershttps://api.ddog-gov.com/api/v2/on-call/schedules/{schedule_id}/respondershttps://api.us2.ddog-gov.com/api/v2/on-call/schedules/{schedule_id}/respondershttps://api.uk1.datadoghq.com/api/v2/on-call/schedules/{schedule_id}/respondershttps://api.datadoghq.com/api/v2/on-call/schedules/{schedule_id}/respondershttps://api.us3.datadoghq.com/api/v2/on-call/schedules/{schedule_id}/respondershttps://api.us5.datadoghq.com/api/v2/on-call/schedules/{schedule_id}/responders

Overview

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.

Response

OK

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 ShiftData id.

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.

type [required]

enum

Teams resource type. Allowed enum values: teams

default: teams

type [required]

enum

Schedules resource type. Allowed enum values: schedules

default: schedules

<type=users>

object

User object returned by the API.

attributes

object

Attributes of user object returned by the API.

created_at

date-time

The ISO 8601 timestamp of when the user account was created.

disabled

boolean

Whether the user account is deactivated. Disabled users cannot log in.

email

string

The email address of the user, used for login and notifications.

handle

string

The unique handle (username) of the user, typically matching their email prefix.

icon

string

URL of the user's profile icon, typically a Gravatar URL derived from the email address.

last_login_time

date-time

The ISO 8601 timestamp of the user's most recent login, or null if the user has never logged in.

mfa_enabled

boolean

Whether multi-factor authentication (MFA) is enabled for the user's account.

modified_at

date-time

The ISO 8601 timestamp of when the user account was last modified.

name

string

The full display name of the user as shown in the Datadog UI.

service_account

boolean

Whether this is a service account rather than a human user. Service accounts are used for programmatic API access.

status

string

The current status of the user account (for example, Active, Pending, or Disabled).

title

string

The job title of the user (for example, "Senior Engineer" or "Product Manager").

uuid

string

The globally unique identifier (UUID) of the user.

verified

boolean

Whether the user's email address has been verified.

id

string

ID of the user.

relationships

object

Relationships of the user object returned by the API.

org

object

Relationship to an organization.

data [required]

object

Relationship to organization object.

id [required]

string

ID of the organization.

type [required]

enum

Organizations resource type. Allowed enum values: orgs

default: orgs

other_orgs

object

Relationship to organizations.

data [required]

[object]

Relationships to organization objects.

id [required]

string

ID of the organization.

type [required]

enum

Organizations resource type. Allowed enum values: orgs

default: orgs

other_users

object

Relationship to users.

data [required]

[object]

Relationships to user objects.

id [required]

string

A unique identifier that represents the user.

type [required]

enum

Users resource type. Allowed enum values: users

default: users

roles

object

Relationship to roles.

data

[object]

An array containing type and the unique identifier of a role.

id

string

The unique identifier of the role.

type

enum

Roles type. Allowed enum values: roles

default: roles

type

enum

Users resource type. Allowed enum values: users

default: users

{
  "data": {
    "attributes": {
      "scheduled_at": "2024-05-07T02:53:01.000000000Z"
    },
    "id": "3653d3c6-0c75-11ea-ad28-fb5701eabc7d-1715054400",
    "relationships": {
      "responders": {
        "data": [
          {
            "id": "3653d3c6-0c75-11ea-ad28-fb5701eabc7d-1715054400-current",
            "type": "schedule_oncall_responder"
          }
        ]
      },
      "schedule": {
        "data": {
          "id": "3653d3c6-0c75-11ea-ad28-fb5701eabc7d",
          "type": "schedules"
        }
      }
    },
    "type": "schedule_oncall_responders"
  },
  "included": [
    {
      "attributes": {
        "position": "current"
      },
      "id": "3653d3c6-0c75-11ea-ad28-fb5701eabc7d-1715054400-current",
      "relationships": {
        "shifts": {
          "data": [
            {
              "id": "00000000-0000-0000-0000-000000000000",
              "type": "shifts"
            }
          ]
        }
      },
      "type": "schedule_oncall_responder"
    },
    {
      "attributes": {
        "end": "2024-05-08T02:53:01.000000000Z",
        "start": "2024-05-07T02:53:01.000000000Z"
      },
      "id": "00000000-0000-0000-0000-000000000000",
      "relationships": {
        "user": {
          "data": {
            "id": "00000000-aba1-0000-0000-000000000000",
            "type": "users"
          }
        }
      },
      "type": "shifts"
    },
    {
      "attributes": {
        "email": "test@test.com",
        "name": "Test User",
        "status": "active"
      },
      "id": "00000000-aba1-0000-0000-000000000000",
      "type": "users"
    }
  ]
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Unauthorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Forbidden

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Found

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  # Path parameters
export schedule_id="3653d3c6-0c75-11ea-ad28-fb5701eabc7d"
# Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/on-call/schedules/${schedule_id}/responders" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
"""
Get on-call responders for a schedule returns "OK" response
"""

from os import environ
from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.on_call_api import OnCallApi

# there is a valid "schedule" in the system
SCHEDULE_DATA_ID = environ["SCHEDULE_DATA_ID"]

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = OnCallApi(api_client)
    response = api_instance.get_schedule_on_call_responders(
        schedule_id=SCHEDULE_DATA_ID,
    )

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
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>" python3 "example.py"
# Get on-call responders for a schedule returns "OK" response

require "datadog_api_client"
api_instance = DatadogAPIClient::V2::OnCallAPI.new

# there is a valid "schedule" in the system
SCHEDULE_DATA_ID = ENV["SCHEDULE_DATA_ID"]
p api_instance.get_schedule_on_call_responders(SCHEDULE_DATA_ID)

Instructions

First install the library and its dependencies and then save the example to example.rb and run following commands:

    
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>" rb "example.rb"
// Get on-call responders for a schedule returns "OK" response

package main

import (
	"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"
)

func main() {
	// there is a valid "schedule" in the system
	ScheduleDataID := 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())

	if err != 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)
}

Instructions

First install the library and its dependencies and then save the example to main.go and run following commands:

    
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>" go run "main.go"
// Get on-call responders for a schedule returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.OnCallApi;
import com.datadog.api.client.v2.model.ScheduleOnCallResponders;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    OnCallApi apiInstance = new OnCallApi(defaultClient);

    // there is a valid "schedule" in the system
    String SCHEDULE_DATA_ID = System.getenv("SCHEDULE_DATA_ID");

    try {
      ScheduleOnCallResponders result = apiInstance.getScheduleOnCallResponders(SCHEDULE_DATA_ID);
      System.out.println(result);
    } catch (ApiException e) {
      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();
    }
  }
}

Instructions

First install the library and its dependencies and then save the example to Example.java and run following commands:

    
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>" java "Example.java"
// Get on-call responders for a schedule returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_on_call::GetScheduleOnCallRespondersOptionalParams;
use datadog_api_client::datadogV2::api_on_call::OnCallAPI;

#[tokio::main]
async fn main() {
    // there is a valid "schedule" in the system
    let schedule_data_id = std::env::var("SCHEDULE_DATA_ID").unwrap();
    let configuration = datadog::Configuration::new();
    let api = OnCallAPI::with_config(configuration);
    let resp = api
        .get_schedule_on_call_responders(
            schedule_data_id.clone(),
            GetScheduleOnCallRespondersOptionalParams::default(),
        )
        .await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}

Instructions

First install the library and its dependencies and then save the example to src/main.rs and run following commands:

    
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";

const configuration = client.createConfiguration();
const apiInstance = new v2.OnCallApi(configuration);

// there is a valid "schedule" in the system
const SCHEDULE_DATA_ID = process.env.SCHEDULE_DATA_ID as string;

const params: 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));

Instructions

First install the library and its dependencies and then save the example to example.ts and run following commands:

    
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>" tsc "example.ts"