---
title: Checks
description: Create and manage monitoring checks that query data on a schedule and generate notification statuses in InfluxDB OSS v2.
url: https://docs.influxdata.com/influxdb/v2/api/checks/
estimated_tokens: 3728
product: InfluxDB OSS v2
version: v2
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb/v2/api/checks/
---

[Download InfluxDB API Spec](/openapi/influxdb-oss-v2-api.yml)

Create and manage monitoring checks that query data on a schedule and generate notification statuses in InfluxDB OSS v2.

GET`/api/v2/checks`

### List all checks

#### Parameters

##### Query parameters

`offset`integer

The offset for pagination.
The number of records to skip.

For more information about pagination parameters, see [Pagination](/influxdb/v2/api/#tag/Pagination).

`limit`integer

Limits the number of records returned. Default is `20`.

Default:`20`

`orgID`requiredstring

Only show checks that belong to a specific organization ID.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "http://localhost:8086/api/v2/checks?orgID=ORGID" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200A list of checks

`checks`object[]

`links`string

defaultUnexpected error

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

POST`/api/v2/checks`

### Add new check

#### Request bodyrequired

Check to create

Content-Type:`application/json`

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "http://localhost:8086/api/v2/checks" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json"
```

#### Responses

201Check created

defaultUnexpected error

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

GET`/api/v2/checks/{checkID}`

### Retrieve a check

#### Parameters

##### Path parameters

`checkID`requiredstring

The check ID.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "http://localhost:8086/api/v2/checks/{checkID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200The check requested

defaultUnexpected error

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

PUT`/api/v2/checks/{checkID}`

### Update a check

#### Parameters

##### Path parameters

`checkID`requiredstring

The check ID.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

#### Request bodyrequired

Check update to apply

Content-Type:`application/json`

Example request[Ask AI about this](#)

```sh
curl --request PUT \
  "http://localhost:8086/api/v2/checks/{checkID}" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json"
```

#### Responses

200An updated check

404The check was not found

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

defaultUnexpected error

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

PATCH`/api/v2/checks/{checkID}`

### Update a check

#### Parameters

##### Path parameters

`checkID`requiredstring

The check ID.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

#### Request bodyrequired

Check update to apply

Content-Type:`application/json`

`description`string

`name`string

`status`string

Allowed:`active`, `inactive`

Example request[Ask AI about this](#)

```sh
curl --request PATCH \
  "http://localhost:8086/api/v2/checks/{checkID}" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "description": "DESCRIPTION",
  "name": "NAME",
  "status": "active"
}'
```

#### Responses

200An updated check

404The check was not found

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

defaultUnexpected error

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

DELETE`/api/v2/checks/{checkID}`

### Delete a check

#### Parameters

##### Path parameters

`checkID`requiredstring

The check ID.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "http://localhost:8086/api/v2/checks/{checkID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

204Delete has been accepted

404The check was not found

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

defaultUnexpected error

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

GET`/api/v2/checks/{checkID}/labels`

### List all labels for a check

#### Parameters

##### Path parameters

`checkID`requiredstring

The check ID.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "http://localhost:8086/api/v2/checks/{checkID}/labels" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200A list of all labels for a check

`labels`string

`links`string

defaultUnexpected error

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

POST`/api/v2/checks/{checkID}/labels`

### Add a label to a check

#### Parameters

##### Path parameters

`checkID`requiredstring

The check ID.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

#### Request bodyrequired

Label to add

Content-Type:`application/json`

`labelID`requiredstring

A label ID.
Specifies the label to attach.

Example request[Ask AI about this](#)

```sh
curl --request POST \
  "http://localhost:8086/api/v2/checks/{checkID}/labels" \
  --header "Authorization: Bearer INFLUX_TOKEN" \
  --header "Content-Type: application/json" \
  --data-raw '{
  "labelID": "LABELID"
}'
```

#### Responses

201The label was added to the check

`label`string

`links`string

defaultUnexpected error

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

DELETE`/api/v2/checks/{checkID}/labels/{labelID}`

### Delete label from a check

#### Parameters

##### Path parameters

`checkID`requiredstring

The check ID.

`labelID`requiredstring

The ID of the label to delete.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request DELETE \
  "http://localhost:8086/api/v2/checks/{checkID}/labels/{labelID}" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

204Delete has been accepted

404Check or label not found

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

defaultUnexpected error

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

GET`/api/v2/checks/{checkID}/query`

### Retrieve a check query

#### Parameters

##### Path parameters

`checkID`requiredstring

The check ID.

##### Header parameters

`Zap-Trace-Span`string

OpenTracing span context

Example request[Ask AI about this](#)

```sh
curl --request GET \
  "http://localhost:8086/api/v2/checks/{checkID}/query" \
  --header "Authorization: Bearer INFLUX_TOKEN"
```

#### Responses

200The check query requested

`flux`string

400Invalid request

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

404Check not found

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.

defaultUnexpected error

`code`requiredstring

code is the machine-readable error code.

Allowed:`internal error`, `not implemented`, `not found`, `conflict`, `invalid`, `unprocessable entity`, `empty value`, `unavailable`, `forbidden`, `too many requests`, `unauthorized`, `method not allowed`, `request too large`, `unsupported media type`

`err`string

Stack of errors that occurred during processing of the request. Useful for debugging.

`message`string

Human-readable message.

`op`string

Describes the logical code operation when the error occurred. Useful for debugging.