---
title: Issues API
description: Programmatically work with Issues via the Cronitor 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. {% .lead %}

See our [Alerts & Issues docs](/docs/alerts) for general information on using Issues to communicate about problems and our [Status Pages docs](/docs/status-pages) for publishing issues publicly.

---

## Quick Start

### Create an Issue
```bash
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
```bash
curl https://cronitor.io/api/issues -u API_KEY:
```

### Update Issue State
```bash
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
```bash
POST https://cronitor.io/api/issues
```

### Request Body
```json
{
    "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
```bash
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
```bash
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
```bash
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
```json
{
    "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
```bash
GET https://cronitor.io/api/issues
```

#### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `state` | string[] | Filter by issue state(s). Multiple values supported |
| `severity` | string[] | Filter by severity level(s). Multiple values supported |
| `statuspage` | string | Filter by status page key |
| `group` | string[] | Filter by monitor group key(s) |
| `job` | string[] | Filter by monitor key(s) |
| `component` | string[] | Filter by status page component key(s) |
| `check` | string[] | Filter by check monitor key(s) |
| `heartbeat` | string[] | Filter by heartbeat monitor key(s) |
| `site` | string[] | Filter by site monitor key(s) |
| `tag` | string[] | Filter by monitor tag(s) |
| `type` | string[] | Filter by monitor type(s) |
| `env` | string | Filter by environment key |
| `search` | string | Search in issue names and associated monitor names/keys/codes |
| `time` | string | Time range filter (e.g., "24h", "7d", "30d") |
| `orderBy` | string | Sort order: "started", "-started", "relevance", "-relevance" |
| `page` | integer | Page number for pagination |
| `pageSize` | integer | Number of results per page (max 1000) |

#### Expansion Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `withStatusPageDetails` | boolean | Include detailed status page information |
| `withMonitorDetails` | boolean | Include detailed monitor information |
| `withAlertDetails` | boolean | Include alert history details |
| `withComponentDetails` | boolean | Include status page component details |

#### Examples

##### Basic Issue Listing
```bash
curl https://cronitor.io/api/issues -u API_KEY:
```

##### Filter by State
```bash
curl "https://cronitor.io/api/issues?state=unresolved&state=investigating" -u API_KEY:
```

##### Filter by Severity
```bash
curl "https://cronitor.io/api/issues?severity=outage&severity=minor_outage" -u API_KEY:
```

##### Search Issues
```bash
curl "https://cronitor.io/api/issues?search=database" -u API_KEY:
```

##### Filter by Time Range
```bash
curl "https://cronitor.io/api/issues?time=7d&orderBy=-started" -u API_KEY:
```

##### Filter by Monitor Groups
```bash
curl "https://cronitor.io/api/issues?group=web-services&group=databases" -u API_KEY:
```

##### Filter by Environment
```bash
curl "https://cronitor.io/api/issues?env=production" -u API_KEY:
```

##### Complex Filtering with Expansion
```bash
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
```bash
GET https://cronitor.io/api/issues/:issueKey
```

#### Example
```bash
curl https://cronitor.io/api/issues/c096dd184de20330 -u API_KEY:
```

#### Response
```json
{
    "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
```bash
PUT https://cronitor.io/api/issues/:issueKey
```

### Request Body
```json
{
    "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
```bash
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{"state": "resolved"}' \
    https://cronitor.io/api/issues/c096dd184de20330
```

#### Add Issue Update
```bash
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
```bash
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
```bash
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
```bash
POST https://cronitor.io/api/issues/bulk
```

### Supported Actions

#### Delete Multiple Issues
```json
{
    "action": "delete",
    "issues": ["issue1", "issue2", "issue3"]
}
```

#### Change State for Multiple Issues
```json
{
    "action": "change_state",
    "issues": ["issue1", "issue2", "issue3"],
    "state": "resolved"
}
```

#### Assign Multiple Issues
```json
{
    "action": "assign_to",
    "issues": ["issue1", "issue2", "issue3"],
    "assign_to": "engineer@example.com"
}
```

### Examples

#### Bulk Delete Issues
```bash
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
```bash
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
```bash
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
```bash
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
```json
{
    "message": "Bulk action completed successfully",
    "processed_count": 3,
    "total_requested": 3
}
```

---

## Deleting Issues

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

### Endpoint
```bash
DELETE https://cronitor.io/api/issues/:issueKey
```

### Example
```bash
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:** `