> Documentation index for AI agents: https://docs.pagerduty.com/llms.txt # List users `GET https://api.pagerduty.com/scim/v2/Users` Retrieves a list of users based on the provided query parameters. Scoped OAuth requires: `users.read` ## Authorization - **apiKey** (apiKey) — `Authorization` header. A [General Access API Key](https://support.pagerduty.com/main/docs/api-access-keys#generate-a-general-access-rest-api-key) with format `Token token=` - **bearerToken** (http) — HTTP bearer. An [App OAuth Token](https://docs.pagerduty.com/developer/private-apps) with format `Bearer ` ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `startIndex` | integer | | The 1-based index of the first result. | | `count` | integer | | Specifies the desired maximum number of query results per page. | | `filter` | string | | A filter expression to apply to the query. The only supported filters are by userName and externalId. | ## Response 200 SCIM User List ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `Resources` | array of object | yes | A multi-valued list of complex objects containing the requested resources. Default: `[]`. | | `Resources[].active` | boolean | yes | A Boolean value indicating the User's administrative status. When set to false, the user will be deleted. All users are created as active by default. It is an error to attempt to create a user with the `active` field set to `false`. Default: `true`. | | `Resources[].displayName` | string | yes | The name of the User, suitable for display to end-users. The name SHOULD be the full name of the User being described, if known. Min length: 1. Max length: 255. | | `Resources[].entitlements` | array of object | | A list containing the User's entitlements. PagerDuty Users have a single entitlement representing the User's license. The `value` field of this item must be set to the User's license ID, and the `type` field must be set to `license`. The license is not required to be set when creating a user. If not set, a default license will be assigned. Valid license IDs can be fetched from the PagerDuty Public API: https://developer.pagerduty.com/api-reference/4c10cb38f7381-list-licenses. Min items: 1. Max items: 1. | | `Resources[].entitlements[].type` | string | yes | One of: `license`. | | `Resources[].entitlements[].value` | string | yes | | | `Resources[].externalId` | string | | A unique identifier for the User, set by the SCIM client. The SCIM client is responsible for ensuring that the value is unique across all Users. Min length: 1. Max length: 100. | | `Resources[].id` | string | yes | A unique identifier for a SCIM resource as defined by the service provider. The identifier is unique across the service provider's entire set of resources. It is a stable, non-reassignable identifier that does not change when the same resource is returned in subsequent requests. The ID must always be treated as a case-sensitive opaque string. Min length: 26. Max length: 100. | | `Resources[].meta` | object | yes | Read-only. | | `Resources[].meta.resourceType` | string | yes | A label indicating the resource type of the resource. Read-only. One of: `User`. | | `Resources[].roles` | array of object | yes | A list containing the User's role. PagerDuty Users have a single role and the list will always contain a single item. The only supported role type at this time is "base", which maps to the user's base account role in PagerDuty. Min items: 1. Max items: 1. | | `Resources[].roles[].primary` | boolean | yes | One of: `true`. | | `Resources[].roles[].type` | string | yes | One of: `base`. | | `Resources[].roles[].value` | string | yes | | | `Resources[].schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:schemas:core:2.0:User"]`. Min items: 1. Items must be unique. | | `Resources[].timezone` | string \| null | | The User's case-sensitive time zone. Must be a valid IANA time zone identifier. Write-only. | | `Resources[].title` | string \| null | | The job title of the User. | | `Resources[].userName` | string (email) | yes | A unique identifier for the User, typically used by the user to directly authenticate to the service provider. Each User MUST include a non-empty userName value. This identifier MUST be unique across the service provider's entire set of Users. Min length: 1. Max length: 100. | | `itemsPerPage` | integer | yes | The number of resources returned in a list response page. Default: `100`. Minimum: 0. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:ListResponse"]`. Min items: 1. Items must be unique. | | `startIndex` | integer | yes | The 1-based index of the first result in the current set of query results. Default: `1`. Minimum: 1. | | `totalResults` | integer | yes | The total number of results matching the client query. Default: `0`. Minimum: 0. | ## Response 400 Bad Request ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 401 Unauthorized ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 403 Forbidden ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## Response 500 Internal Server Error ### `application/scim+json` | Field | Type | Required | Description | |---|---|---|---| | `detail` | string | yes | Detailed error explanation. | | `schemas` | array of string (uri) | yes | URIs that indicate the schemas used in data. Default: `["urn:ietf:params:scim:api:messages:2.0:Error"]`. Min items: 1. Items must be unique. | | `scimType` | string | | SCIM error type. One of: `invalidFilter`, `tooMany`, `uniqueness`, `mutability`, `invalidSyntax`, `invalidPath`, `noTarget`, `invalidValue`, `invalidVers`, `sensitive`. | | `status` | string | yes | HTTP status code for the error. | ## 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).