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

# List services

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

List existing Services.

A service may represent an application, component, or team you wish to open incidents against.

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

Scoped OAuth requires: `services.read`

## Authorization

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

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `query` | string |  | Filters the result, showing only the records whose name matches the query. |
| `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`. |
| `team_ids[]` | array of string |  | An array of team IDs. Only results related to these teams will be returned. Account must have the `teams` ability to use this parameter. Items must be unique. |
| `time_zone` | string (tzinfo) |  | Time zone in which results will be rendered. This will default to the account time zone. |
| `sort_by` | string |  | Used to specify the field you wish to sort the results on. One of: `name`, `name:asc`, `name:desc`. Default: `name`. |
| `include[]` | string |  | Array of additional details to include. One of: `escalation_policies`, `teams`, `integrations`, `auto_pause_notifications_parameters`. Items must be unique. |
| `name` | string |  | Filters the results, showing only services with the specified name. |

## 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 services.

### `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. |
| `services` | array of object | yes |  |
| `services[].id` | string |  | Read-only. |
| `services[].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. |
| `services[].type` | string | yes | The type of object being created. One of: `service`. Default: `service`. |
| `services[].self` | string \| null (url) |  | the API show URL at which the object is accessible. Read-only. |
| `services[].html_url` | string \| null (url) |  | a URL at which the entity is uniquely displayed in the Web app. Read-only. |
| `services[].name` | string |  | The name of the service. |
| `services[].description` | string |  | The user-provided description of the service. |
| `services[].auto_resolve_timeout` | integer |  | Time in seconds that an incident is automatically resolved if left open for that long. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `14400`. |
| `services[].acknowledgement_timeout` | integer |  | Time in seconds that an incident changes to the Triggered State after being Acknowledged. Value is `null` if the feature is disabled. Value must not be negative. Setting this field to `0`, `null` (or unset in POST request) will disable the feature. Default: `1800`. |
| `services[].created_at` | string (date-time) |  | The date/time when this service was created. Read-only. |
| `services[].status` | string |  | The current state of the Service. Valid statuses are: - `active`: The service is enabled and has no open incidents. This is the only status a service can be created with. - `warning`: The service is enabled and has one or more acknowledged incidents. - `critical`: The service is enabled and has one or more triggered incidents. - `maintenance`: The service is under maintenance, no new incidents will be triggered during maintenance mode. - `disabled`: The service is disabled and will not have any new triggered incidents. One of: `active`, `warning`, `critical`, `maintenance`, `disabled`. Default: `active`. |
| `services[].last_incident_timestamp` | string (date-time) |  | The date/time when the most recent incident was created for this service. Read-only. |
| `services[].escalation_policy` | object | yes |  |
| `services[].escalation_policy.id` | string | yes | Read-only. |
| `services[].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. |
| `services[].escalation_policy.type` | string | yes | One of: `escalation_policy_reference`. |
| `services[].escalation_policy.self` | string \| null (url) |  | the API show URL at which the object is accessible. Read-only. |
| `services[].escalation_policy.html_url` | string \| null (url) |  | a URL at which the entity is uniquely displayed in the Web app. Read-only. |
| `services[].response_play` |  |  | Response plays associated with this service. **Deprecated.** |
| `services[].teams` | array of object |  | The set of teams associated with this service. Read-only. |
| `services[].teams[].id` | string | yes | Read-only. |
| `services[].teams[].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. |
| `services[].teams[].type` | string | yes | One of: `team_reference`. |
| `services[].teams[].self` | string \| null (url) |  | the API show URL at which the object is accessible. Read-only. |
| `services[].teams[].html_url` | string \| null (url) |  | a URL at which the entity is uniquely displayed in the Web app. Read-only. |
| `services[].integrations` | array of object |  | An array containing Integration objects that belong to this service. If `integrations` is passed as an argument, these are full objects - otherwise, these are references. Read-only. |
| `services[].integrations[].id` | string | yes | Read-only. |
| `services[].integrations[].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. |
| `services[].integrations[].type` | string | yes | One of: `aws_cloudwatch_inbound_integration_reference`, `cloudkick_inbound_integration_reference`, `event_transformer_api_inbound_integration_reference`, `generic_email_inbound_integration_reference`, `generic_events_api_inbound_integration_reference`, `keynote_inbound_integration_reference`, `nagios_inbound_integration_reference`, `pingdom_inbound_integration_reference`, `sql_monitor_inbound_integration_reference`, `events_api_v2_inbound_integration_reference`, `inbound_integration_reference`. |
| `services[].integrations[].self` | string \| null (url) |  | the API show URL at which the object is accessible. Read-only. |
| `services[].integrations[].html_url` | string \| null (url) |  | a URL at which the entity is uniquely displayed in the Web app. Read-only. |
| `services[].incident_urgency_rule` | object |  |  |
| `services[].incident_urgency_rule.type` | string |  | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. |
| `services[].incident_urgency_rule.urgency` | string |  | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. |
| `services[].incident_urgency_rule.during_support_hours` | object |  |  |
| `services[].incident_urgency_rule.during_support_hours.type` | string |  | The type of incident urgency: whether it's constant, or it's dependent on the support hours. One of: `constant`, `use_support_hours`. Default: `constant`. |
| `services[].incident_urgency_rule.during_support_hours.urgency` | string |  | The incidents' urgency, if type is constant. One of: `low`, `high`, `severity_based`. Default: `high`. |
| `services[].incident_urgency_rule.outside_support_hours` | object |  | Same fields as `services[].incident_urgency_rule.during_support_hours` above. |
| `services[].support_hours` | object |  |  |
| `services[].support_hours.type` | string |  | The type of support hours. One of: `fixed_time_per_day`. Default: `fixed_time_per_day`. |
| `services[].support_hours.time_zone` | string (activesupport-time-zone) |  | The time zone for the support hours. |
| `services[].support_hours.days_of_week` | array of integer |  | Read-only. |
| `services[].support_hours.start_time` | string (time) |  | The support hours' starting time of day (date portion is ignored) |
| `services[].support_hours.end_time` | string (time) |  | The support hours' ending time of day (date portion is ignored) |
| `services[].scheduled_actions` | array of object |  | An array containing scheduled actions for the service. |
| `services[].scheduled_actions[].type` | string | yes | The type of schedule action. Must be set to urgency_change. One of: `urgency_change`. |
| `services[].scheduled_actions[].at` | object | yes | Represents when scheduled action will occur. |
| `services[].scheduled_actions[].at.type` | string | yes | Must be set to named_time. One of: `named_time`. |
| `services[].scheduled_actions[].at.name` | string | yes | Designates either the start or the end of support hours. One of: `support_hours_start`, `support_hours_end`. |
| `services[].scheduled_actions[].to_urgency` | string | yes | Urgency level. Must be set to high. One of: `high`. |
| `services[].addons` | array of object |  | The array of Add-ons associated with this service. Read-only. |
| `services[].addons[].id` | string | yes | Read-only. |
| `services[].addons[].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. |
| `services[].addons[].type` | string | yes | One of: `full_page_addon_reference`, `incident_show_addon_reference`. |
| `services[].addons[].self` | string \| null (url) |  | the API show URL at which the object is accessible. Read-only. |
| `services[].addons[].html_url` | string \| null (url) |  | a URL at which the entity is uniquely displayed in the Web app. Read-only. |
| `services[].addons[].src` | string (url) |  | The URL source of the Addon. |
| `services[].addons[].name` | string |  | The user entered name of the Addon. |
| `services[].alert_creation` | string |  | Whether a service creates only incidents, or both alerts and incidents. A service must create alerts in order to enable incident merging. * "create_incidents" - The service will create one incident and zero alerts for each incoming event. * "create_alerts_and_incidents" - The service will create one incident and one associated alert for each incoming event. This attribute has been deprecated as all services will be migrated to use alerts and incidents. Afterward, the incident only service setting will no longer be available. For details, please refer to the knowledge base: https://support.pagerduty.com/docs/alerts#enable-and-disable-alerts-on-a-service. **Deprecated.** One of: `create_incidents`, `create_alerts_and_incidents`. Default: `create_alerts_and_incidents`. |
| `services[].alert_grouping_parameters` | one of: object \| object |  | Alert Grouping Parameters. **Deprecated.** |
| `services[].alert_grouping_parameters.type` | string \| null |  | (Alert Grouping Parameters) One of: `time`, `intelligent`, `content_based`, `null`. |
| `services[].alert_grouping_parameters.config` | one of: object \| object \| object |  | (Alert Grouping Parameters) |
| `services[].alert_grouping_parameters.config.time_window` | integer |  | (Intelligent Alert Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours. To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 and 3600. Minimum: 300. Maximum: 3600. |
| `services[].alert_grouping_parameters.config.recommended_time_window` | integer |  | (Intelligent Alert Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. |
| `services[].alert_grouping_parameters.config.timeout` | integer |  | (Time Grouping) The duration in minutes within which to automatically group incoming Alerts. To continue grouping Alerts until the Incident is resolved, set this value to 0. Minimum: 1. Maximum: 1440. |
| `services[].alert_grouping_parameters.config.aggregate` | string |  | (Content Only Grouping) Whether Alerts should be grouped if `all` or `any` specified fields match. If `all` is selected, an exact match on every specified field name must occur for Alerts to be grouped. If `any` is selected, Alerts will be grouped when there is an exact match on at least one of the specified fields. One of: `all, any`. |
| `services[].alert_grouping_parameters.config.fields` | array of string |  | (Content Only Grouping) An array of strings which represent the fields with which to group against. Depending on the aggregate, Alerts will group if some or all the fields match. |
| `services[].alert_grouping_parameters.config.time_window` | integer |  | (Content Only Grouping) The maximum amount of time allowed between Alerts. Any Alerts arriving greater than `time_window` seconds apart will not be grouped together. This is a rolling time window up to 24 hours and is counted from the most recently grouped alert. The window is extended every time a new alert is added to the group, up to 24 hours (24 hours only applies to single-service settings). To use the "recommended_time_window," set the value to 0, otherwise the value must be between 300 <= time_window <= 3600 or 86400(i.e. 24 hours). Minimum: 300. Maximum: 86400. |
| `services[].alert_grouping_parameters.config.recommended_time_window` | integer |  | (Content Only Grouping) In order to ensure your Service has the optimal grouping window, we use data science to calculate your Service's average Alert inter-arrival time. We encourage customers to use this value. Please set `time_window` to 0 to use the `recommended_time_window`. Read-only. |
| `services[].alert_grouping_parameters.id` | string |  | (Alert Grouping Settings Reference) id of the related alert grouping setting. Read-only. |
| `services[].alert_grouping_parameters.type` | string |  | (Alert Grouping Settings Reference) type of reference eg. alert_grouping_setting_reference. Read-only. |
| `services[].alert_grouping_parameters.summary` | string |  | (Alert Grouping Settings Reference) an explanation of this reference. Read-only. |
| `services[].alert_grouping_parameters.self` | string |  | (Alert Grouping Settings Reference) link to api endpoint for this setting. Read-only. |
| `services[].alert_grouping_parameters.html_url` | string |  | (Alert Grouping Settings Reference) link to the ui page to edit the setting. Read-only. |
| `services[].alert_grouping` | string |  | Defines how alerts on this service will be automatically grouped into incidents. Note that the alert grouping features are available only on certain plans. There are three available options: * null - No alert grouping on the service. Each alert will create a separate incident; * "time" - All alerts within a specified duration will be grouped into the same incident. This duration is set in the `alert_grouping_timeout` setting (described below). Available on Standard, Enterprise, and Event Intelligence plans; * "intelligent" - Alerts will be intelligently grouped based on a machine learning model that looks at the alert summary, timing, and the history of grouped alerts. Available on Enterprise and Event Intelligence plans This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** One of: `time`, `intelligent`. |
| `services[].alert_grouping_timeout` | integer |  | The duration in minutes within which to automatically group incoming alerts. This setting applies only when `alert_grouping` is set to `time`. To continue grouping alerts until the Incident is resolved, set this value to `0`. This attribute has been deprecated and configuration via [Alert Grouping Settings](https://docs.pagerduty.com/developer/api/reference/rest/alert-grouping-settings/post-alert-grouping-settings) resource is encouraged. **Deprecated.** |
| `services[].auto_pause_notifications_parameters` | object |  | Defines how alerts on this service are automatically suspended for a period of time before triggering, when identified as likely being transient. Note that automatically pausing notifications is only available on certain plans. |
| `services[].auto_pause_notifications_parameters.enabled` | boolean |  | Indicates whether alerts should be automatically suspended when identified as transient. Default: `false`. |
| `services[].auto_pause_notifications_parameters.timeout` | integer |  | Indicates in seconds how long alerts should be suspended before triggering. To automatically select the recommended timeout for a service, set this value to `0`. One of: `0`, `120`, `180`, `300`, `600`, `900`. |
| `services[].auto_pause_notifications_parameters.recommended_timeout` | integer |  | The recommended timeout setting for this service based on prior alert patterns. One of: `120`, `180`, `300`, `600`, `900`. |

Example: Response Example

```json
{
  "services": [
    {
      "id": "PIJ90N7",
      "summary": "My Application Service",
      "type": "service",
      "self": "https://api.pagerduty.com/services/PIJ90N7",
      "html_url": "https://subdomain.pagerduty.com/service-directory/PIJ90N7",
      "name": "My Application Service",
      "auto_resolve_timeout": 14400,
      "acknowledgement_timeout": 600,
      "created_at": "2015-11-06T11:12:51-05:00",
      "status": "active",
      "alert_creation": "create_alerts_and_incidents",
      "alert_grouping_parameters": {
        "type": "intelligent"
      },
      "integrations": [
        {
          "id": "PQ12345",
          "type": "generic_email_inbound_integration_reference",
          "summary": "Email Integration",
          "self": "https://api.pagerduty.com/services/PIJ90N7/integrations/PQ12345",
          "html_url": "https://subdomain.pagerduty.com/services/PIJ90N7/integrations/PQ12345"
        }
      ],
      "escalation_policy": {
        "id": "PT20YPA",
        "type": "escalation_policy_reference",
        "summary": "Another Escalation Policy",
        "self": "https://api.pagerduty.com/escalation_policies/PT20YPA",
        "html_url": "https://subdomain.pagerduty.com/escalation_policies/PT20YPA"
      },
      "teams": [
        {
          "id": "PQ9K7I8",
          "type": "team_reference",
          "summary": "Engineering",
          "self": "https://api.pagerduty.com/teams/PQ9K7I8",
          "html_url": "https://subdomain.pagerduty.com/teams/PQ9K7I8"
        }
      ],
      "incident_urgency_rule": {
        "type": "use_support_hours",
        "during_support_hours": {
          "type": "constant",
          "urgency": "high"
        },
        "outside_support_hours": {
          "type": "constant",
          "urgency": "low"
        }
      },
      "support_hours": {
        "type": "fixed_time_per_day",
        "time_zone": "America/Lima",
        "start_time": "09:00:00",
        "end_time": "17:00:00",
        "days_of_week": [
          1,
          2,
          3,
          4,
          5
        ]
      },
      "scheduled_actions": [
        {
          "type": "urgency_change",
          "at": {
            "type": "named_time",
            "name": "support_hours_start"
          },
          "to_urgency": "high"
        }
      ],
      "auto_pause_notifications_parameters": {
        "enabled": true,
        "timeout": 300
      }
    }
  ],
  "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. |

## 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).