Cronitor API

Issues API

The Issues API allows you to create, manage, and publish issues to your status pages. Issues help you communicate about problems as they occur - either privately with teammates or publicly on your status pages. This guide provides comprehensive documentation for all issue operations including bulk actions, filtering, and advanced management features.

See our Alerts & Issues docs for general information on using Issues to communicate about problems and our Status Pages docs for publishing issues publicly.

Quick Start

Create an Issue

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "Service Unavailable",
        "severity": "outage",
        "assigned_to": "developer@example.com"
    }' \
    https://cronitor.io/api/issues

List All Issues

curl https://cronitor.io/api/issues -u API_KEY:

Update Issue State

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{"state": "resolved"}' \
    https://cronitor.io/api/issues/c096dd184de20330

Creating Issues

Create a new issue to track and communicate about problems affecting your services.

Endpoint

POST https://cronitor.io/api/issues

Request Body

{
    "name": "Service Unavailable",
    "severity": "outage",
    "state": "investigating",
    "assigned_to": "developer@example.com",
    "environment": "production",
    "statuspages": ["988ae49478f12afd"],
    "affected_components": ["comp123", "comp456"],
    "updates": [
        {
            "message": "We are investigating reports of service unavailability",
            "state": "investigating"
        }
    ]
}

Examples

Basic Issue Creation

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "Database Connection Issues",
        "severity": "minor_outage"
    }' \
    https://cronitor.io/api/issues

Issue with Status Page Publication

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "API Performance Degradation",
        "severity": "degraded_performance",
        "state": "investigating",
        "assigned_to": "ops-team@example.com",
        "statuspages": ["988ae49478f12afd"],
        "affected_components": ["api-component"],
        "updates": [
            {
                "message": "We are investigating reports of slower than normal API response times",
                "state": "investigating"
            }
        ]
    }' \
    https://cronitor.io/api/issues

Issue with Multiple Updates

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "name": "Scheduled Maintenance",
        "severity": "maintenance",
        "state": "monitoring",
        "updates": [
            {
                "message": "Maintenance window has begun",
                "state": "monitoring"
            },
            {
                "message": "Database migration in progress",
                "state": "update"
            }
        ]
    }' \
    https://cronitor.io/api/issues

Response

{
    "key": "c096dd184de20330",
    "name": "Service Unavailable",
    "severity": "outage",
    "state": "investigating",
    "started": "2023-06-02T09:39:31Z",
    "ended": null,
    "duration": null,
    "environment": {
        "key": "production",
        "name": "Production"
    },
    "assigned_to": "developer@example.com",
    "created_by": {
        "kind": "user",
        "name": "John Doe"
    },
    "statuspages": ["988ae49478f12afd"],
    "affected_components": ["comp123"],
    "monitors": [],
    "updates": [
        {
            "key": "upd123",
            "message": "We are investigating reports of service unavailability",
            "state": "investigating",
            "timestamp": "2023-06-02T09:39:31Z",
            "created": "2023-06-02T09:39:31Z",
            "updated": "2023-06-02T09:39:31Z"
        }
    ],
    "alerts": [],
    "created": "2023-06-02T09:39:31Z",
    "updated": "2023-06-02T09:39:31Z"
}

Retrieving Issues

List All Issues

Retrieve all issues in your account with optional filtering and pagination.

Endpoint

GET https://cronitor.io/api/issues

Query Parameters

ParameterTypeDescription
statestring[]Filter by issue state(s). Multiple values supported
severitystring[]Filter by severity level(s). Multiple values supported
statuspagestringFilter by status page key
groupstring[]Filter by monitor group key(s)
jobstring[]Filter by monitor key(s)
componentstring[]Filter by status page component key(s)
checkstring[]Filter by check monitor key(s)
heartbeatstring[]Filter by heartbeat monitor key(s)
sitestring[]Filter by site monitor key(s)
tagstring[]Filter by monitor tag(s)
typestring[]Filter by monitor type(s)
envstringFilter by environment key
searchstringSearch in issue names and associated monitor names/keys/codes
timestringTime range filter (e.g., "24h", "7d", "30d")
orderBystringSort order: "started", "-started", "relevance", "-relevance"
pageintegerPage number for pagination
pageSizeintegerNumber of results per page (max 1000)

Expansion Parameters

ParameterTypeDescription
withStatusPageDetailsbooleanInclude detailed status page information
withMonitorDetailsbooleanInclude detailed monitor information
withAlertDetailsbooleanInclude alert history details
withComponentDetailsbooleanInclude status page component details

Examples

Basic Issue Listing
curl https://cronitor.io/api/issues -u API_KEY:
Filter by State
curl "https://cronitor.io/api/issues?state=unresolved&state=investigating" -u API_KEY:
Filter by Severity
curl "https://cronitor.io/api/issues?severity=outage&severity=minor_outage" -u API_KEY:
Search Issues
curl "https://cronitor.io/api/issues?search=database" -u API_KEY:
Filter by Time Range
curl "https://cronitor.io/api/issues?time=7d&orderBy=-started" -u API_KEY:
Filter by Monitor Groups
curl "https://cronitor.io/api/issues?group=web-services&group=databases" -u API_KEY:
Filter by Environment
curl "https://cronitor.io/api/issues?env=production" -u API_KEY:
Complex Filtering with Expansion
curl "https://cronitor.io/api/issues?state=unresolved&severity=outage&withMonitorDetails=true&withAlertDetails=true" -u API_KEY:

Get Individual Issue

Retrieve a specific issue by its key.

Endpoint

GET https://cronitor.io/api/issues/:issueKey

Example

curl https://cronitor.io/api/issues/c096dd184de20330 -u API_KEY:

Response

{
    "key": "c096dd184de20330",
    "name": "Service Unavailable",
    "severity": "outage",
    "state": "resolved",
    "started": "2023-06-02T09:39:31Z",
    "ended": "2023-06-02T11:15:22Z",
    "duration": 5751,
    "environment": {
        "key": "production",
        "name": "Production"
    },
    "assigned_to": "developer@example.com",
    "created_by": {
        "kind": "user",
        "name": "John Doe"
    },
    "statuspages": ["988ae49478f12afd"],
    "affected_components": ["comp123"],
    "monitors": [
        {
            "key": "api-health-check",
            "name": "API Health Check",
            "type": "check",
            "passing": true,
            "paused": false,
            "active": true,
            "group": {
                "name": "Web Services",
                "key": "web-services"
            }
        }
    ],
    "updates": [
        {
            "key": "upd123",
            "message": "We are investigating reports of service unavailability",
            "state": "investigating",
            "timestamp": "2023-06-02T09:39:31Z",
            "created": "2023-06-02T09:39:31Z",
            "updated": "2023-06-02T09:39:31Z"
        },
        {
            "key": "upd124",
            "message": "Issue has been identified and fix is being deployed",
            "state": "identified",
            "timestamp": "2023-06-02T10:15:00Z",
            "created": "2023-06-02T10:15:00Z",
            "updated": "2023-06-02T10:15:00Z"
        },
        {
            "key": "upd125",
            "message": "Service has been restored and is operating normally",
            "state": "resolved",
            "timestamp": "2023-06-02T11:15:22Z",
            "created": "2023-06-02T11:15:22Z",
            "updated": "2023-06-02T11:15:22Z"
        }
    ],
    "alerts": [],
    "created": "2023-06-02T09:39:31Z",
    "updated": "2023-06-02T11:15:22Z"
}

Updating Issues

Modify existing issues to change their state, add updates, or adjust other properties.

Endpoint

PUT https://cronitor.io/api/issues/:issueKey

Request Body

{
    "name": "Updated Issue Name",
    "severity": "minor_outage",
    "state": "monitoring",
    "assigned_to": "new-assignee@example.com",
    "statuspages": ["988ae49478f12afd"],
    "affected_components": ["comp123", "comp456"],
    "updates": [
        {
            "message": "Additional update on the issue",
            "state": "monitoring"
        }
    ]
}

Examples

Update Issue State

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{"state": "resolved"}' \
    https://cronitor.io/api/issues/c096dd184de20330

Add Issue Update

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{
        "updates": [
            {
                "message": "We have identified the root cause and are implementing a fix",
                "state": "identified"
            }
        ]
    }' \
    https://cronitor.io/api/issues/c096dd184de20330

Change Assignment and Severity

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{
        "assigned_to": "senior-engineer@example.com",
        "severity": "outage",
        "updates": [
            {
                "message": "Escalating issue due to increased impact",
                "state": "investigating"
            }
        ]
    }' \
    https://cronitor.io/api/issues/c096dd184de20330

Publish to Status Page

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{
        "statuspages": ["988ae49478f12afd"],
        "affected_components": ["api-component", "database-component"],
        "updates": [
            {
                "message": "Issue is now being tracked publicly on our status page",
                "state": "update"
            }
        ]
    }' \
    https://cronitor.io/api/issues/c096dd184de20330

Bulk Actions

Perform operations on multiple issues simultaneously for efficient management.

Endpoint

POST https://cronitor.io/api/issues/bulk

Supported Actions

Delete Multiple Issues

{
    "action": "delete",
    "issues": ["issue1", "issue2", "issue3"]
}

Change State for Multiple Issues

{
    "action": "change_state",
    "issues": ["issue1", "issue2", "issue3"],
    "state": "resolved"
}

Assign Multiple Issues

{
    "action": "assign_to",
    "issues": ["issue1", "issue2", "issue3"],
    "assign_to": "engineer@example.com"
}

Examples

Bulk Delete Issues

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "action": "delete",
        "issues": ["c096dd184de20330", "d123ee285ef30441", "e234ff396fg40552"]
    }' \
    https://cronitor.io/api/issues/bulk

Bulk State Change

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "action": "change_state",
        "issues": ["c096dd184de20330", "d123ee285ef30441"],
        "state": "resolved"
    }' \
    https://cronitor.io/api/issues/bulk

Bulk Assignment

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "action": "assign_to",
        "issues": ["c096dd184de20330", "d123ee285ef30441"],
        "assign_to": "team-lead@example.com"
    }' \
    https://cronitor.io/api/issues/bulk

Bulk Resolve with Update Message

curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "action": "change_state",
        "issues": ["c096dd184de20330", "d123ee285ef30441", "e234ff396fg40552"],
        "state": "resolved"
    }' \
    https://cronitor.io/api/issues/bulk

Response

{
    "message": "Bulk action completed successfully",
    "processed_count": 3,
    "total_requested": 3
}

Deleting Issues

Remove issues from your account. Deleted issues cannot be recovered.

Endpoint

DELETE https://cronitor.io/api/issues/:issueKey

Example

curl --user API_KEY: \
    --request DELETE \
    https://cronitor.io/api/issues/c096dd184de20330

Response

Returns HTTP 204 (No Content) on successful deletion.

Issue Attributes Reference

Core Attributes

name (string, required)

The display name of this issue. Used to identify the issue in alerts, within the Cronitor application, and on status pages.

Example: "Database Connection Issues"

severity (string, optional)

The severity level of the issue. Affects how the issue is displayed and prioritized.

Options:

  • missing_data - Data collection issues
  • operational - Normal operations
  • maintenance - Planned maintenance
  • degraded_performance - Performance issues
  • minor_outage - Limited service disruption
  • outage - Major service disruption

Default: outage

state (string, optional)

The current state of the issue lifecycle.

Options:

  • unresolved - Issue is open and unaddressed
  • investigating - Team is investigating the issue
  • identified - Root cause has been identified
  • monitoring - Fix implemented, monitoring
  • resolved - Issue is fully resolved
  • update - General update (used for issue updates only)

Default: `

Previous
Monitors
Next
Metrics