Attach alerts to an incident from provided data

Cancel a running investigation.

Check if any at-risk responders (based on On-Call Health analysis) are scheduled for on-call.

Integrates with On-Call Health (oncallhealth.ai) to identify responders with elevated workload health risk and checks if they are scheduled during the specified period. Optionally recommends safe replacement responders.

Privacy: This tool surfaces identifiable employee workload health data from On-Call Health. It is an opt-in feature — an administrator must explicitly configure the ONCALLHEALTH_API_KEY environment variable to enable it.

Available only in self-hosted deployments. Requires ONCALLHEALTH_API_KEY environment variable.

Check if specific users are scheduled for on-call in a date range.

Use this to verify if at-risk users (from On-Call Health) are scheduled, or to check availability before assigning new shifts.

Returns scheduled users with their shifts and total hours, plus users who are not scheduled. Shift times and hours are clipped to the requested window; date-only end dates include that entire UTC day.

Collect a bounded working set of incidents across multiple pages for audits and analysis.

Use this instead of list_incidents when you want a compact batch of incidents in one tool call, while keeping payload size under control.

Argument caps: max_results <= 100, batch_size between 10 and 100. Values outside those bounds are clamped and reported, not rejected.

Count logs matching a Logs explorer query, grouped by service, index, severity or an attribute key (@http.status_code). Answers questions like "errors per service in the last 6h" (filter[query]=severity:error, filter[from]=now-6h, group_by=service). Values are ordered by count, largest first; meta.total counts every matching log, and each value's logs_query drills into its rows with GET /v1/observability/logs (null for a blank value, which the query syntax cannot select, or when the drill-down would exceed the query limits: 512 characters or 20 clauses). A log can carry an attribute key more than once (log, resource and scope attributes), so attribute counts can add up to more than meta.total; when logs match but none have the attribute, data is empty and meta.warnings has code attribute_missing. Requires a personal or Global API key (Team API Keys are group-scoped and get 403 unsupported_api_key) or an OAuth token with the obs.logs:read (or all) scope, and the Observability logs read permission. A Global API key uses its service user's Observability role, which starts as the team's default Observability role. Limited to 60 requests per minute per token; on this endpoint the X-RateLimit-* headers report that per-minute budget, not the default API limit. Every 429 returns the errors envelope with code rate_limited and a Retry-After header.

Creates a new alert from provided data

Creates a new alert event

Creates a new alert group. Note: For enhanced functionality and future compatibility, consider using the advanced alert grouping with conditions field instead of the legacy group_by_alert_title, group_by_alert_urgency, and attributes fields.

Creates a new alert route from provided data. Note: This endpoint requires access to Advanced Alert Routing. If you're unsure whether you have access to this feature, please contact Rootly customer support.

Asynchronous Rule Creation

For organizations with large numbers of routing rules, Rootly supports asynchronous rule processing to improve performance. When enabled, rule creation happens in the background.

Asynchronous processing is also applied automatically, whether or not it is enabled for your organization, when a request carries a rule graph too large to save within the request timeout. Size is measured in total dependent records — rules plus their condition groups, conditions and destinations — and for an update it includes the rules already on the route, not just those in the payload.

Important: Whenever rules are processed asynchronously, the rules list in the API response will not be up-to-date immediately after creation. You should refetch the alert route, or poll the async rule creation status endpoint with the request_id you supplied, to confirm the rules have landed.

If you experience slow operations when managing alert routes with many rules, contact Rootly customer support to enable asynchronous rule processing for your organization.

Creates a new alert routing rule from provided data. Note: If you are an advanced alert routing user, you should use the Alert Routes endpoint instead of this endpoint. If you don't know whether you are an advanced user, please contact Rootly customer support.

Creates a new alert source from provided data

Creates a new alert urgency from provided data

Creates a new catalog from provided data

Creates a new Catalog Entity from provided data

Deprecated: This endpoint is deprecated, please use the fields attribute on catalog entities or native catalog endpoints (teams, services, functionalities, incident_types, causes, environments) to set field values instead.

Creates a new Catalog Entity Property from provided data.

Creates a new Catalog Property - returns catalog_properties type

Creates a new cause from provided data

[DEPRECATED] Use form field endpoints instead. Creates a new custom field from provided data

Creates a new custom form from provided data

Creates a new dashboard from provided data

Creates a new environment from provided data

Creates a new escalation level from provided data

Creates a new escalation level from provided data

Creates a new escalation path from provided data

Creates a new escalation policy from provided data

Creates a new form_field from provided data

Creates a new form_field_option from provided data

Creates a new form_set from provided data

Creates a new functionality from provided data

Creates a new heartbeat from provided data

Create an incident with a scoped set of fields for agent-driven workflows.

Creates a new action item from provided data

[DEPRECATED] Use form field endpoints instead. Creates a new incident custom field selection from provided data

Creates a new event from provided data

Creates a new incident form field selection from provided data

Creates a new incident_type from provided data

Creates a new Live Call Router from provided data

Creates a new On-Call Role from provided data

Creates a new on call shadow configuration from provided data

Recommend replacement responders for an override shift.

Finds users in the same schedule rotation who are not already heavily loaded during the period.

Returns recommended replacements sorted by current load (lowest first), plus a ready-to-use override payload for the top recommendation.

Creates a new override shift from provided data. If any existing override shifts overlap with the specified time range, they will be automatically deleted and replaced by the new override. This endpoint is idempotent: re-sending an identical override (same user and same start/end time) returns the existing override with a 200 status and does not recreate it.

Creates a new playbook from provided data

Creates a new pulse from provided data

Creates a new retrospective process from provided data

Creates a new schedule from provided data

Creates a new schedule rotation from provided data

Creates a new schedule rotation active day from provided data

Creates a new schedule rotation user from provided data

Creates a new service from provided data

Creates a new severity from provided data

Creates a new status page from provided data

Creates a new template from provided data

Creates a new Sub-Status from provided data

Creates a new team from provided data

Creates a new user email address from provided data

Creates a new user notification rule from provided data

Creates a new user phone number from provided data

Creates a new workflow from provided data

Creates a new workflow form field condition from provided data

Creates a new workflow group from provided data

Creates a new workflow run from provided data

Creates a new workflow task from provided data

🔍 Find historically similar incidents using ML similarity analysis - CRITICAL for incident response.

WHEN TO USE: • EARLY in incident response to learn from past similar issues • When you're unsure about root cause or resolution approach • Before escalating to find if this is a known pattern • For post-incident analysis to identify recurring issues

Provide either incident_id OR incident_description (e.g., 'website is down', 'database timeout errors'). Use status_filter to limit to specific incident statuses or leave empty for all incidents.

Argument caps: max_results <= 20. Values outside the bounds are clamped and reported, not rejected.

Retrieves a specific alert by id

Get alert details by short_id or alert URL. Use this when a user pastes an alert URL or short_id from a pager notification and wants to investigate the alert.

Retrieves a specific alert_event by id

Retrieves a specific alert group by id

Get a specific alert route by id. Note: This endpoint requires access to Advanced Alert Routing. If you're unsure whether you have access to this feature, please contact Rootly customer support.

Optional Parameters

• show_nested_ids (query parameter): When set to true, the response will include IDs for all nested resources (destinations, condition_groups, conditions). This is useful when you need to reference these nested resources for updates or deletions via PATCH requests.

Example: GET /v1/alert_routes/{id}?show_nested_ids=true

Retrieves a specific alert routing rule by id. Note: If you are an advanced alert routing user, you should use the Alert Routes endpoint instead of this endpoint. If you don't know whether you are an advanced user, please contact Rootly customer support.

Retrieves a specific alert source by id

Retrieves a specific alert urgency by id

Retrieves a specific catalog by id

Retrieves a specific Catalog Entity by id

Deprecated: This endpoint is deprecated, please use include=fields on catalog entities or native catalog endpoints (teams, services, functionalities, incident_types, causes, environments) to retrieve field values instead.

Retrieves a specific Catalog Entity Property by id.

Retrieves a specific Catalog Property by id - returns catalog_properties type

Retrieves a specific cause by id

Get current user

Retrieves a specific custom_field by id

[DEPRECATED] Use form field endpoints instead. Retrieves a specific custom field option by id

Retrieves a specific custom form by id

Retrieves a specific dashboard by id

Retrieves a specific dashboard panel by id

Retrieves a specific environment by id

Retrieves a specific escalation level by id

Retrieves a specific escalation path by id

Retrieves a specific escalation policy by id

Retrieves a specific form_field by id

Retrieves a specific form_field_option by id

Retrieves a specific form_field_placement by id

Retrieves a specific form_field_placement_condition by id

Retrieves a specific form_set by id

Retrieves a specific form_set_condition by id

Retrieves a specific functionality by id

Get functionality incidents chart

Get functionality uptime chart

Retrieves a specific heartbeat by id

Retrieve a single incident with PIR-related fields for direct verification.

Retrieves a specific incident_action_item by id

[DEPRECATED] Use form field endpoints instead. Retrieves a specific incident custom field selection by id

Retrieves a specific incident form field selection by id

Read what was said on an incident's calls (Rootly Meeting Scribe).

Returns the spoken transcript of each recorded call for the incident, as text per speaker turn, alongside Scribe's own summary. Covers Google Meet, Zoom and Microsoft Teams calls that Scribe recorded.

Use this to catch up on a call you missed, or to pull decisions and actions out of an incident bridge. Recordings where nobody spoke are skipped rather than returned empty.

Fetch the written retrospective for one incident.

Answers "what did we learn from INC-4460" in a single call. Returns the document's title, content and status alongside the incident it belongs to, and reports the incident's retrospective progress so a blank document is distinguishable from one nobody has started.

The route exists only in this direction: /post_mortems cannot be filtered by incident, and the document carries no reference back to one, so the id has to come from the incident's own relationship. Doing that here keeps a caller from having to know it. Use list_incident_post_mortems to search across retrospectives instead.

Retrieves a specific incident retrospective step by id

Retrieves a specific incident_sub_status by id

Retrieves a specific incident_type by id

Get an investigation's verdict: summary, root cause, confidence, hypotheses, evidence, causal chain and open_questions (what Rootly couldn't verify, so you can check them with tools only you have).

Follow a running investigation. Returns new steps and tool calls since after_cursor, waiting up to wait_seconds for them. Keep calling with after_cursor=next_cursor until done is true.

Retrieves a specific Live Call Router by id

Retrieve a single meeting recording session including its status, duration, speaker count, word count, and transcript summary.

Get current on-call handoff summary. Shows who's currently on-call and who's next. Optionally fetch incidents (set include_incidents=True, but slower). Each responder's role is their On-Call role (e.g. Responder, Admin); shifts themselves carry no role.

Use filter_by_region=True with a timezone to see only people on-call during business hours in that region (e.g., timezone='Asia/Tokyo', filter_by_region=True shows only APAC on-call during APAC business hours).

Useful for:

• Quick on-call status checks

• Daily handoff meetings

• Regional on-call status (APAC, EU, Americas)

• Team coordination across timezones

Retrieves a specific On-Call Role by id

Get compact on-call schedule summary for a date range.

Returns one entry per user per schedule (not raw shifts), with aggregated hours. Optimized for AI agent context windows.

Use this instead of list_shifts when you need:

• Aggregated hours per responder

• Schedule coverage overview

• Responder load analysis with warnings

One row per user per schedule, so the response stays the same size whether the range is a week or a year. For individual shift times, or for one person's schedule, use list_shifts instead.

Ranges longer than the upstream cap are split into windows and merged automatically.

Retrieves a specific On Call Shadow configuration by ID

📊 Get on-call workload metrics and shift statistics - ESSENTIAL for fairness and planning.

WHEN TO USE: • Monthly/quarterly reviews of on-call distribution • Before adjusting schedules to ensure fair workload • For management reporting on on-call burden • When investigating potential on-call burnout

Returns shift counts, total hours, and statistics grouped by user, schedule, or team.

Examples:

• Monthly report: start_date='2025-10-01', end_date='2025-10-31'

• Specific user: start_date='2025-10-01', end_date='2025-10-31', user_ids='123,456'

• Specific team: team_ids='team-1' (will query schedules for that team first)

Retrieves a specific override shift by id

Retrieves a specific playbook by id

Retrieves a specific playbook_task by id

Retrieves a specific pulse by id

Retrieves a specific retrospective process by id

Retrieves a specific Retrospective Process Group by id

Retrieves a specific retrospective step by id

Retrieves a specific schedule by id

Retrieves a specific schedule rotation by id

List shifts for one schedule over a date range.

Replaces the generated getScheduleShifts, which passed the range straight through and failed with Datetime range exceeds 1 month on anything longer than the upstream accepts. Ranges longer than that are split into windows and merged here, so a two-month question is a normal request.

Use list_shifts instead when the question spans schedules or filters by user.

Get the Rootly MCP server version.

Returns the current version of the deployed MCP server. Useful for checking if the server has been updated.

Retrieves a specific service by id

Get service incidents chart

Get service uptime chart

Retrieves a specific severity by id

Retrieves a specific shift coverage request.

Get incidents and alerts that occurred during a specific shift or time period.

Useful for:

• Shift handoff summaries showing what happened during the shift

• Post-shift debriefs and reporting

• Incident analysis by time period

• Understanding team workload during specific shifts

Returns incident details including severity, status, duration, and basic summary.

Retrieves a specific status page by id

Retrieves a specific status_page_template by id

Retrieves a specific Sub-Status by id

Retrieves a specific team by id

Get team incidents chart

Retrieves a specific user by id

Retrieves all email addresses for the specified user

Retrieves all phone numbers for the specified user

Retrieves a specific workflow by id

Retrieves a specific workflow form field condition by id

Retrieves a specific workflow group by id

Retrieves a specific workflow_task by id

List alert_events

List alert groups

List all alert routes for the current team with filtering and pagination. Note: This endpoint requires access to Advanced Alert Routing. If you're unsure whether you have access to this feature, please contact Rootly customer support.

List alert routing rules. Note: If you are an advanced alert routing user, you should use the Alert Routes endpoint instead of this endpoint. If you don't know whether you are an advanced user, please contact Rootly customer support.

List alerts

List alert sources

List alert urgencies

List all action items for an organization

List meeting recordings across the organization. Returns the current user's standalone recordings plus incident-backed recordings the user can access. Supports filtering by status, platform, and created_by.

Read the Rootly audit log: who changed which configuration object, when, and what changed.

Each record carries the action, the acting user, the source, and the before-and-after value of every modified field. Use it to answer "who changed this escalation policy", "what did this workflow look like before", or to collect change evidence for a compliance review.

Covers roughly 60 resource types at the object level and is retained indefinitely. Two limits worth knowing: schedule rotations, escalation levels and shift overrides are not audited, and sign-in events are kept separately from this log.

Returns a single page of at most 25 records, newest first, alongside total_matching so a wider search can be narrowed with the filters. It does not walk the whole log, so a full compliance export belongs on the REST endpoint rather than here.

Requires an API token whose role has the "Audits - read" permission.

List Catalog Entities

Deprecated: This endpoint is deprecated, please use include=fields on catalog entities or native catalog endpoints (teams, services, functionalities, incident_types, causes, environments) to retrieve field values instead.

List Catalog Entity Properties.

List Catalog Properties - returns catalog_properties type

List catalogs

List causes

[DEPRECATED] Use form field endpoints instead. List Custom fields

List custom forms

List dashboards

List all available Rootly API endpoints with their descriptions.

List environments

List escalation levels

List escalation levels

List escalation paths

List escalation policies

List form_field_options

List form_fields

List form_sets. Without filter[resource_type], returns incident form sets and, when Problem Management is enabled, problem form sets. Pass filter[resource_type]=incident to list only incident form sets.

List functionalities

List heartbeats

List incident action items

List incident alerts

[DEPRECATED] Use form field endpoints instead. List incident custom field selections

List incident events

List incident form field selections

Browse retrospectives across incidents.

Answers "the last five retrospectives", "published ones for this team since June", or "how many are still draft". Each result carries the document's analysis -- summary, causes, impact, actions. A recognised Timeline is dropped and the record says so with timeline_omitted, because a minute-by-minute log is a third of a document and rarely what a browse is after. What remains is still capped, and a record cut that way carries content_truncated with its real content_chars. Use get_incident_retrospective for one document whole, Timeline included and nothing cut.

Filtering happens upstream for status, severity, team, service and dates. Free-text search is not offered here because the API's search matches titles only, and titles are generated from the incident name -- it cannot find a retrospective by what it says. Use get_incident_retrospective when the incident is already known.

List role assignments for an incident (who is Commander, Scribe, etc.).

Returns one entry per defined role with role metadata and the assigned user (or user_id: null for roles that are defined on the incident but not yet assigned). Use this to answer questions like "who is the incident commander?", "is there a postmortem owner?", or "list all roles for INC-4460".

Implementation note: this wraps GET /v1/incidents/{id}?include=roles and flattens the JSON:API included array of incident_role_assignments into a flat table so callers don't need to walk the relationships graph.

🚨 List incidents with structured filters - ESSENTIAL for incident response.

WHEN TO USE: • During incident response to check for related ongoing incidents • For shift handoffs to review recent incidents by team/service • For post-incident analysis to find patterns by severity/date range • For audit workflows requiring specific filtering criteria

Use this when you need date-range, team, service, severity, or status filters. For simple text searches, prefer search_incidents instead.

Argument caps: page_size <= 100. Values outside the bounds are clamped and reported, not rejected.

List incident types

List AI SRE investigations you can see, newest first.

List Live Call Routers

List all meeting recording sessions for an incident. Returns recordings sorted by session number. Each recording represents one bot session with its own transcript, status, and metadata.

Search Rootly Observability logs with the Logs explorer query syntax (service:, severity:, index:, trace_id:, @attribute:value, OR inside field groups, - negation, * prefix, free text). Rows are newest first, clipped and redacted. meta.query and meta.window echo the effective query and window. Requires a personal or Global API key (Team API Keys are group-scoped and get 403 unsupported_api_key) or an OAuth token with the obs.logs:read (or all) scope, and the Observability logs read permission. A Global API key uses its service user's Observability role, which starts as the team's default Observability role. Limited to 60 requests per minute per token; on this endpoint the X-RateLimit-* headers report that per-minute budget, not the default API limit. Every 429 returns the errors envelope with code rate_limited and a Retry-After header.

List log patterns (clustered log templates) with counts against the previous window of the same length. Only service:, severity: and pattern: filters apply; others are echoed in meta.ignored_filters. Each pattern's logs_query drills into matching rows with GET /v1/observability/logs; it is omitted when that query would exceed the /logs length or clause limits. Requires a personal or Global API key (Team API Keys are group-scoped and get 403 unsupported_api_key) or an OAuth token with the obs.logs:read (or all) scope, and the Observability logs read permission. A Global API key uses its service user's Observability role, which starts as the team's default Observability role. Limited to 60 requests per minute per token; on this endpoint the X-RateLimit-* headers report that per-minute budget, not the default API limit. Every 429 returns the errors envelope with code rate_limited and a Retry-After header.

List On-Call Roles

List shadow shifts for schedule

List override shifts

List playbooks

List pulses

List retrospective processes

List schedule rotation active days

List schedule rotations

List schedule rotation users

List schedules

List services

List severities

List active shift coverage requests for a schedule.

List on-call shifts with reliable filtering, enrichment, and MCP-level pagination.

Unlike the raw API, this tool:

• Actually filters by user_ids (client-side filtering)

• Includes user_name, user_email, schedule_name, team_name

• Calculates total_hours for each shift

• Returns a predictable paginated result for MCP clients

Use this instead of the auto-generated listShifts when you need user filtering or dependable pagination on large tenants.

Answers questions about individual shifts: who is on call at a given time, when a handoff happens, which shifts were overrides, or one person's schedule (via user_ids). For questions about totals across a team -- hours per responder, coverage, load -- use get_oncall_schedule_summary, whose response size depends on team size rather than on how long a range you asked for.

Ranges longer than the upstream cap are split into windows and merged automatically, so a multi-month range is a normal request.

List status pages

List status page templates

List Sub-Statuses

List teams

List user notification rules

List users

List workflow form field conditions

List workflow groups

List workflow runs

List workflows

List workflow tasks

Updates an alert route. Note: This endpoint requires access to Advanced Alert Routing. If you're unsure whether you have access to this feature, please contact Rootly customer support.

Search incidents with flexible pagination control.

Use page_number=0 to fetch all matching results across multiple pages. Use page_number>0 to fetch a specific page.

max_results (also accepted as limit) caps how many incidents come back in either mode: across pages when page_number=0, and within the page otherwise. Left unset, a single page returns page_size incidents and page_number=0 stops at 5.

Argument caps: page_size <= 20, max_results <= 10. Values outside those bounds are clamped and reported, not rejected.

Start an AI SRE investigation on one alert or incident. Then follow it with get_investigation_progress.

💡 Get actionable solution recommendations from similar resolved incidents - KEY for incident response.

WHEN TO USE: • AFTER find_related_incidents to get specific resolution steps • When team is stuck on how to resolve the current incident • To speed up incident resolution with proven solutions • For training new responders on resolution patterns

Provide either incident_id OR title/description. Defaults to resolved incidents for solution mining.

Argument caps: max_solutions <= 10. Values outside the bounds are clamped and reported, not rejected.

Updates an alert

Updates a specific alert event. Only alert events with kind 'note' (user-created notes) can be updated. System-generated events are immutable to maintain audit trail integrity.

Update a specific alert group by id. Note: For enhanced functionality and future compatibility, consider using the advanced alert grouping with conditions field instead of the legacy group_by_alert_title, group_by_alert_urgency, and attributes fields.

Update a specific alert route by id. Note: This endpoint requires access to Advanced Alert Routing. If you're unsure whether you have access to this feature, please contact Rootly customer support.

Asynchronous Rule Creation

For organizations with large numbers of routing rules, Rootly supports asynchronous rule processing to improve performance. When enabled, rule updates happen in the background.

Asynchronous processing is also applied automatically, whether or not it is enabled for your organization, when a request carries a rule graph too large to save within the request timeout. Size is measured in total dependent records — rules plus their condition groups, conditions and destinations — and includes the rules already on the route, not just those in the payload, so a small payload against a large route may still be processed asynchronously.

Important: Whenever rules are processed asynchronously, the rules list in the API response will not be up-to-date immediately after update. You should refetch the alert route, or poll the async rule creation status endpoint with the request_id you supplied, to confirm the rules have landed.

If you experience slow operations when managing alert routes with many rules, contact Rootly customer support to enable asynchronous rule processing for your organization.

Update a specific alert routing rule by id. Note: If you are an advanced alert routing user, you should use the Alert Routes endpoint instead of this endpoint. If you don't know whether you are an advanced user, please contact Rootly customer support.

Update a specific alert source by id

Update a specific alert urgency by id

Update a specific catalog by id

Update a specific Catalog Entity by id

Deprecated: This endpoint is deprecated, please use the fields attribute on catalog entities or native catalog endpoints (teams, services, functionalities, incident_types, causes, environments) to set field values instead.

Update a specific Catalog Entity Property by id.

Update a specific catalog_property by id - returns catalog_properties type

Update a specific cause by id

[DEPRECATED] Use form field endpoints instead. Update a specific custom field by id

[DEPRECATED] Use form field endpoints instead. Update a specific custom field option by id

Update a specific custom form by id

Update a specific dashboard by id

Update a specific dashboard panel by id

Update a specific environment by id

Update a specific escalation level by id

Update a specific escalation path by id

Update a specific escalation policy by id

Update a specific form_field by id

Update a specific form_field_option by id

Update a specific form_field_placement by id

Update a specific form_field_placement_condition by id

Update a specific form_set by id

Update a specific form_set_condition by id

Update a specific functionality by id

Update a specific heartbeat by id

Update native incident fields via PUT /v1/incidents/{id}.

Only the arguments you provide are sent, so unspecified fields — including the lifecycle status — are left untouched.

Update a specific incident action item by id

[DEPRECATED] Use form field endpoints instead. Update a specific incident custom field selection by id

Update a specific incident form field selection by id

Update a specific incident retrospective step by id

Update a specific incident_sub_status by id

Update a specific incident_type by id

Update a specific Live Call Router by id

Update a specific On-Call Role by id

Update a specific on call shadow configuration by id

Update a specific override shift by id

Update a specific playbook by id

Update a specific playbook task by id

Update a specific pulse by id

Updates a specific retrospective process by id

Update a specific Retrospective Process Group by id

Update a specific retrospective step by id

Updates a specific schedule by id

Update a specific schedule rotation by id

Update a specific service by id

Update a specific severity by id

Update a specific status page by id

Update a specific template event by id

Update a specific Sub-Status by id

Update a specific team by id

Update a specific workflow by id

Update a specific workflow form field condition by id

Update a specific workflow group by id

Update a specific workflow task by id