{"id":2177,"library":"pagerduty","title":"PagerDuty Python Client","description":"The `pagerduty` library provides lightweight Python clients for PagerDuty's REST API v2 and Events API v2, built on top of the `httpx` HTTP client. It is the official and actively maintained successor to the `pdpyras` library, offering features like connection pooling, authentication, pagination, and configurable retry logic. The current version is 6.2.1, with a regular release cadence addressing bug fixes, new features, and API endpoint support.","status":"active","version":"6.2.1","language":"en","source_language":"en","source_url":"https://github.com/PagerDuty/python-pagerduty","tags":["pagerduty","api client","incident management","alerting","devops"],"install":[{"cmd":"pip install pagerduty","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"The library uses httpx as its underlying HTTP client since v6.0.0.","package":"httpx"}],"imports":[{"note":"The `pdpyras` module and its classes like `APISession` are deprecated. `pagerduty` is the new module, and `RestApiV2Client` is its equivalent.","wrong":"from pdpyras import APISession","symbol":"RestApiV2Client","correct":"from pagerduty import RestApiV2Client"},{"note":"The `pdpyras` module and its classes like `EventsAPISession` are deprecated. `pagerduty` is the new module, and `EventsApiV2Client` is its equivalent.","wrong":"from pdpyras import EventsAPISession","symbol":"EventsApiV2Client","correct":"from pagerduty import EventsApiV2Client"}],"quickstart":{"code":"import os\nfrom pagerduty import RestApiV2Client\n\n# PagerDuty API Key (recommended: user-scoped or service-specific key)\nPAGERDUTY_API_KEY = os.environ.get('PAGERDUTY_API_KEY', 'YOUR_PAGERDUTY_API_KEY')\n# 'From' email header is required for some actions (e.g., resolving incidents) \n# when using an account-level API key.\nPAGERDUTY_FROM_EMAIL = os.environ.get('PAGERDUTY_FROM_EMAIL', 'your_user@example.com')\n\nif not PAGERDUTY_API_KEY or PAGERDUTY_API_KEY == 'YOUR_PAGERDUTY_API_KEY':\n    print(\"Error: PAGERDUTY_API_KEY environment variable not set or placeholder used.\")\n    exit(1)\n\ntry:\n    # Initialize the REST API client\n    # For account-level API keys, pass default_from for actions requiring a 'From' header\n    client = RestApiV2Client(PAGERDUTY_API_KEY, default_from=PAGERDUTY_FROM_EMAIL)\n\n    # Example: List users\n    print(\"Fetching PagerDuty users...\")\n    users_response = client.get('/users')\n\n    if users_response.is_success:\n        users = users_response.json().get('users', [])\n        for user in users:\n            print(f\"User ID: {user['id']}, Name: {user['name']}, Email: {user['email']}\")\n        print(f\"Successfully fetched {len(users)} users.\")\n    else:\n        print(f\"Error fetching users: {users_response.status_code} - {users_response.text}\")\n        \n    # Example: Create an incident (requires a service API key, not account-level)\n    # This example requires a valid `service_id` and `from` email and a user with permissions\n    # incident_data = {\n    #     \"incident\": {\n    #         \"type\": \"incident\",\n    #         \"title\": \"Test Incident from Python Client\",\n    #         \"service\": {\"id\": \"PXXXXXX\", \"type\": \"service_reference\"},\n    #         \"priority\": {\"id\": \"PXXXXXX\", \"type\": \"priority_reference\"}, # Optional\n    #         \"body\": {\"type\": \"text\", \"details\": \"This is a test incident created via the Python client.\"}\n    #     }\n    # }\n    # create_incident_response = client.post('/incidents', json=incident_data, headers={'From': PAGERDUTY_FROM_EMAIL})\n    # if create_incident_response.is_success:\n    #     print(f\"Incident created: {create_incident_response.json()['incident']['id']}\")\n    # else:\n    #     print(f\"Error creating incident: {create_incident_response.status_code} - {create_incident_response.text}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to initialize the PagerDuty `RestApiV2Client` and perform a basic API call, such as listing users. It highlights the importance of setting the `PAGERDUTY_API_KEY` and, for account-level API keys, the `PAGERDUTY_FROM_EMAIL` header for certain write operations."},"warnings":[{"fix":"Update imports from `pdpyras` to `pagerduty` and refactor client class instantiations according to the `PDPYRAS Migration Guide` in the `python-pagerduty` documentation. For example, change `session = pdpyras.APISession(API_KEY)` to `client = pagerduty.RestApiV2Client(API_KEY)`.","message":"The `pdpyras` library has been deprecated and replaced by `python-pagerduty` (installed as `pagerduty`). This involves a module rename (e.g., `import pdpyras` becomes `import pagerduty`) and significant class renames (e.g., `pdpyras.APISession` is now `pagerduty.RestApiV2Client`, `pdpyras.EventsAPISession` is now `pagerduty.EventsApiV2Client`). Projects should migrate to the new library and its updated class names.","severity":"breaking","affected_versions":"<= v0.x (pdpyras), all `pagerduty` versions migrating from `pdpyras`"},{"fix":"Review any code that directly interacted with the underlying `requests` session or configured proxy settings. Refer to the `httpx` documentation for equivalent configurations.","message":"Version 6.0.0 switched the underlying HTTP client from `requests` to `httpx`. While the developer interface is largely similar, this change introduces breaking changes, particularly in how the client is configured to use a proxy server.","severity":"breaking","affected_versions":">= 6.0.0"},{"fix":"Pass the `default_from` keyword argument during client instantiation (e.g., `client = RestApiV2Client(API_KEY, default_from='user@example.com')`) or set it via `client.default_from = 'user@example.com'`.","message":"When using an account-level PagerDuty API key (created by an administrator), certain API actions, especially those that take action on incidents (e.g., acknowledge, resolve), require a `From` header. This header's value must be the email address of a valid PagerDuty user, otherwise, requests may result in an HTTP 400 error.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If encountering connectivity issues or incorrect data for EU accounts, ensure the `api_url` parameter is set correctly during `RestApiV2Client` or `EventsApiV2Client` initialization. The library may handle this automatically in recent versions, but explicit setting can resolve issues.","message":"For PagerDuty accounts located in the EU service region, the API URL might need to be explicitly configured. While v6.2.0 introduced improvements for supporting EU regions, older versions or specific configurations might still require setting the `api_url` parameter during client initialization to the appropriate EU endpoint (e.g., `https://api.eu.pagerduty.com`).","severity":"gotcha","affected_versions":"<= 6.1.0, potentially some >= 6.2.0 configurations"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}