> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcollate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List and Retrieve Incidents

> List incidents, find them by test case, status, or assignee, and read one incident with its status history through the Collate REST API and Python SDK.

# List and Retrieve Incidents

List incidents, read one incident, and search the incident status history.

> [!NOTE]
>
> The Python examples on this page use the original client (`metadata.ingestion.ometa.ometa_api.OpenMetadata`) because SDK 2.0 (`metadata.sdk`) doesn't include incident operations. For more information, see [Which Python SDK Should I Use?](https://docs.getcollate.io/ai-2-0/developer-guide/sdk/python.md).

## List Incidents as Tasks

List incidents with `GET /v1/tasks`. Set `category=Incident` to return only incidents.

**category** `string`

Set to `Incident`.

**type** `string`

Set to `TestCaseResolution` to return only data quality incidents.

**status** `string`

Task status, for example `Open`, `InProgress`, or `Completed`.

**statusGroup** `string`

`open` or `closed`. Use this instead of `status` to get all open or all closed incidents.

**assignee** `string`

Name of the assigned user or team.

**aboutEntity** `string`

Fully qualified name of the test case the incident is about.

**domain** `string`

Domain of the incident.

**priority** `string`

`Critical`, `High`, `Medium`, or `Low`.

**startTs** `integer`

Return incidents created at or after this Unix epoch timestamp in milliseconds.

**endTs** `integer`

Return incidents created at or before this Unix epoch timestamp in milliseconds.

**fields** `string`

Comma-separated fields to include, for example `payload,assignees,about`.

**limit** `integer` (default: 10)

Number of results per page. Use `before` and `after` for paging.

```bash GET /v1/tasks theme={null}
curl "https://your-company.getcollate.io/api/v1/tasks?category=Incident&type=TestCaseResolution&statusGroup=open&fields=assignees,about,payload&limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

```python GET /v1/tasks theme={null}
from metadata.ingestion.ometa.ometa_api import OpenMetadata
from metadata.generated.schema.entity.services.connections.metadata.openMetadataConnection import (
    OpenMetadataConnection,
)
from metadata.generated.schema.security.client.openMetadataJWTClientConfig import (
    OpenMetadataJWTClientConfig,
)
from metadata.ingestion.ometa.task_models import TaskCategory

server_config = OpenMetadataConnection(
    hostPort="https://your-company.getcollate.io/api",
    authProvider="openmetadata",
    securityConfig=OpenMetadataJWTClientConfig(jwtToken="<YOUR-JWT-TOKEN>"),
)
metadata = OpenMetadata(server_config)

incidents = metadata.list_tasks(
    category=TaskCategory.Incident,
    status_group="open",
    fields=["assignees", "about", "payload"],
    limit=50,
)
for task in incidents.entities:
    print(task.name, task.status)
```

## Retrieve One Incident

Retrieve one incident by ID or by task number.

* By ID: `GET /v1/tasks/{id}`
* By task number: `GET /v1/tasks/name/{taskId}`, for example `TASK-00001`

Both accept `fields` and `include`.

```python theme={null}
from metadata.ingestion.ometa.ometa_api import OpenMetadata
from metadata.generated.schema.entity.services.connections.metadata.openMetadataConnection import (
    OpenMetadataConnection,
)
from metadata.generated.schema.security.client.openMetadataJWTClientConfig import (
    OpenMetadataJWTClientConfig,
)

server_config = OpenMetadataConnection(
    hostPort="https://your-company.getcollate.io/api",
    authProvider="openmetadata",
    securityConfig=OpenMetadataJWTClientConfig(jwtToken="<YOUR-JWT-TOKEN>"),
)
metadata = OpenMetadata(server_config)

task = metadata.get_task("c4f7e2b0-0000-4000-8000-000000000010", fields=["assignees", "about"])
```

### Response

The task response includes these fields:

**id** `string`

UUID of the incident task. This is also the incident `stateId`.

**taskId** `string`

Human-readable task number, for example `TASK-00001`.

**name** `string`

Incident name, in the form `Incident: <test case name>`.

**status** `string`

Task status: `Open`, `InProgress`, or `Completed`.

**workflowStageId** `string`

Current stage: `new`, `ack`, `assigned`, or `resolved`.

**availableTransitions** `array`

Transitions that apply now. Each item has `id`, `label`, `targetStageId`, `targetTaskStatus`, and `requiresComment`.

**assignees** `array`

Users or teams the incident is assigned to.

**about** `object`

Reference to the test case.

**resolution** `object`

Present after the incident is resolved. Includes `type`, `resolvedBy`, `resolvedAt`, `comment`, and `payload` (which contains `testCaseFailureReason`).

## Search Incident History

Use the test case incident status endpoints to search incidents by test case or time and to read the full status history.

| Endpoint | Returns |
| - | - |
| `GET /v1/dataQuality/testCases/testCaseIncidentStatus` | Status records. Filters: `testCaseId`, `testCaseFQN`, `originEntityFQN`, `testCaseResolutionStatusType` (`New`, `Ack`, `Assigned`, `Resolved`), `assignee`, `domain`, `testDefinition`, `owner`, `unowned`, `severity`, `startTs`, `endTs`, `dateField`, `latest`, `limit`, `offset`, `page`. Set `latest=true` to return only the current status of each incident. |
| `GET /v1/dataQuality/testCases/testCaseIncidentStatus/incidentGroups` | Open incidents grouped by table, test definition, or test case owner. See [Group Open Incidents](#group-open-incidents). |
| `GET /v1/dataQuality/testCases/testCaseIncidentStatus/search/list` | The same filters, plus `sortField` and `sortType`. The Incident Manager list uses this endpoint. |
| `GET /v1/dataQuality/testCases/testCaseIncidentStatus/stateId/{stateId}` | Every status record for one incident, in order. Use the incident (task) ID as `stateId`. |
| `GET /v1/dataQuality/testCases/testCaseIncidentStatus/{id}` | One status record. |

Each status record includes these fields:

* `id`, `stateId`, and `timestamp`
* `testCaseResolutionStatusType`
* `testCaseResolutionStatusDetails`: the assignee, or the failure reason and comment
* `updatedBy` and `updatedAt`
* `testCaseReference` and `severity`
* `metrics`: `timeToResponse` and `timeToResolution`, in milliseconds

```bash theme={null}
curl "https://your-company.getcollate.io/api/v1/dataQuality/testCases/testCaseIncidentStatus?latest=true&testCaseResolutionStatusType=New&limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

```python theme={null}
from metadata.ingestion.ometa.ometa_api import OpenMetadata
from metadata.generated.schema.entity.services.connections.metadata.openMetadataConnection import (
    OpenMetadataConnection,
)
from metadata.generated.schema.security.client.openMetadataJWTClientConfig import (
    OpenMetadataJWTClientConfig,
)

server_config = OpenMetadataConnection(
    hostPort="https://your-company.getcollate.io/api",
    authProvider="openmetadata",
    securityConfig=OpenMetadataJWTClientConfig(jwtToken="<YOUR-JWT-TOKEN>"),
)
metadata = OpenMetadata(server_config)

# The Python client has no list method for incident history, so call the path directly
response = metadata.client.get(
    "/dataQuality/testCases/testCaseIncidentStatus",
    {"latest": "true", "limit": 50},
)
```

## Group Open Incidents

Use `GET /v1/dataQuality/testCases/testCaseIncidentStatus/incidentGroups` to count open incidents by test definition, table, or test case owner. The Incident Manager in the UI builds its grouped view from this endpoint. Resolved incidents are never included.

**groupBy** `string` *required*

The dimension to group by: `table`, `testDefinition`, or `owner`.

**status** `string`

Open status to filter by: `New`, `Ack`, or `Assigned`. Repeat the parameter or separate values with commas. A `Resolved` value returns a `400` error.

**assignee** `string`

Name of the current assignee.

**severity** `string`

Current severity to filter by: `Severity1` to `Severity5`. Repeat the parameter or separate values with commas. Use `none` to match incidents that have no severity.

**testCaseFQN** `string`

Fully qualified name of a test case.

**domain** `string`

Domain of the incidents.

**dateField** `string` (default: createdAt)

The incident timestamp that `startTs` and `endTs` apply to: `createdAt` or `updatedAt`.

**startTs** `integer`

Return incidents after this Unix epoch timestamp in milliseconds.

**endTs** `integer`

Return incidents before this Unix epoch timestamp in milliseconds.

**group** `string`

Return only one group. Use the table's fully qualified name, the ID of the test definition or owner, or an empty value for the test cases that nobody owns.

**sortField** `string` (default: incidentCount)

What to order the groups by: `incidentCount`, `severity`, or `lastSeen`. When you sort by `severity` in descending order, the most severe groups come first and the groups with no severity come last.

**sortType** `string` (default: desc)

Direction of the ordering: `asc` or `desc`.

**limit** `integer` (default: 10)

Number of groups to return, from 1 to 1,000.

**offset** `string`

Cursor from the `paging.before` or `paging.after` value of a previous response.

**page** `integer`

A 1-based page to return instead of a cursor. It takes precedence over `offset`.

Each group in the response includes these fields:

* `groupBy`, `id`, `name`, `displayName`, and `fullyQualifiedName`: the table, test definition, or owner that the group represents.
* `incidentCount`: the number of distinct open incidents in the group.
* `severity`: the most critical severity in the group. `Severity1` is the most critical. The field is absent when no incident in the group has a severity.
* `status`: the most actionable status in the group, ranked `Assigned`, then `Ack`, then `New`.
* `statusCounts`: the number of open incidents in each status, most actionable first.
* `assignees`, `assigneeReferences`, and `assigneeCount`: the distinct current assignees.
* `firstSeen` and `lastSeen`: when the earliest open incident in the group was opened, and the most recent status change across the group.
* `trend` and `trendDirection`: the number of incidents opened in each of eight equal time buckets between `firstSeen` and `lastSeen`, and a direction of `Rising`, `Falling`, or `Steady`.
* `tables`, `tableCount`, `testDefinitions`, and `testDefinitionCount`: the related tables and test definitions, with the most open incidents first. The lists are capped, and the count fields hold the full number.

```bash theme={null}
curl "https://your-company.getcollate.io/api/v1/dataQuality/testCases/testCaseIncidentStatus/incidentGroups?groupBy=table&status=New&status=Assigned&sortField=severity&limit=25" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "data": [
    {
      "groupBy": "table",
      "name": "orders",
      "fullyQualifiedName": "svc.db.schema.orders",
      "incidentCount": 4,
      "severity": "Severity2",
      "status": "Assigned",
      "statusCounts": [
        { "status": "Assigned", "count": 2 },
        { "status": "New", "count": 2 }
      ],
      "assigneeCount": 1,
      "trend": [0, 0, 1, 0, 0, 1, 1, 1],
      "trendDirection": "Rising"
    }
  ],
  "paging": { "total": 1 }
}
```

To list the incidents behind a group, call `GET /v1/dataQuality/testCases/testCaseIncidentStatus` with the filter that matches the grouping:

* **Test definition**: `testDefinition`, by name or fully qualified name.
* **Test case owner**: `owner`, the name of a user or team that directly owns the test case. Use `unowned=true` for the test cases that nobody owns. Don't combine `unowned` with `owner`.
* **Table**: `originEntityFQN`, the fully qualified name of the table.

Add `assignee`, `severity`, `domain`, `dateField`, `startTs`, and `endTs` to match the filters that you used for the groups.

## Keep an External Tracker in Sync

Collate doesn't include a built-in Jira integration. Task responses have an `externalReference` field for storing a Jira key, but Collate doesn't sync it for you.

To mirror incidents in a tracker such as Jira:

1. Create a `Notification` alert on the `task` source with a webhook destination. See [Alert for Incident Events](https://docs.getcollate.io/ai-2-0/developer-guide/api-reference/alerts/create.md#alert-for-incident-events).
2. In your receiver, deduplicate on the event `id`. Read `entityType` and the parsed `entity`.
3. Ignore events that aren't incidents (`entity.category` isn't `Incident`).
4. Use the incident ID (`entityId`) as the key that links the Jira issue and the incident, and store it on the issue.
5. On each event, read `entity.workflowStageId` and update the issue.
6. To close the loop, call [Change Incident Status](https://docs.getcollate.io/ai-2-0/developer-guide/api-reference/incidents/update-status.md) when the issue changes in the tracker.
7. Run a periodic `GET /v1/tasks?category=Incident&statusGroup=open` as a safety net, because Collate doesn't automatically resend a webhook that failed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.