Create a project monitor

POST`https://api.spice.ai/v1/projects/{projectId}/monitors`

Creates a project monitor from a runtime template. Requires monitors:write. A monitor evaluates a runtime metric on a schedule and fires when the comparison holds; to fire on matching dataset rows instead, create a data reaction at /v1/projects/{projectId}/reactions.

Authorizations

AuthorizationstringRequired
Bearer <token>. Authentication lists the tokens it accepts.

Path parameters

projectIdintegerRequired
The ID of the project

Header parameters

X-Org-Namestring
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own. A portal session token is bound to none, so it must send this header on every route but GET /v1/orgs (400 org_assertion_required otherwise).
- Pattern: ^[A-Za-z0-9._-]{1,255}$

Body

application/jsonRequired

namestringRequired
Display name. Unique, case-insensitively, among the project's live monitors and data reactions — a collision answers 409.
- Minimum length: 1
- Maximum length: 100
descriptionstring
- Maximum length: 500
kindstring
Optional assertion that templateId names a monitor. A value that disagrees with the template is refused rather than ignored; omit it and the template decides.
- Value: runtime
templateIdstringRequired
The runtime template the monitor evaluates. query_latency_p95 is retained for existing monitors but cannot be used to create new ones; use query_latency_p99. container_cpu is available only on managed projects with a defined CPU limit. A data-reaction template is refused here — create those at /v1/projects/{projectId}/reactions.
- Allowed values: query_failures, query_latency_p95, query_latency_p99, llm_failures, dataset_refresh_errors, http_5xx, flight_failures, memory_working_set, container_cpu, dataset_status, instance_health
specobjectRequired
Monitor parameters. Which properties apply is decided by templateId — each property below names the templates that read it, and a property no monitor template reads is stored rather than rejected. spec is shared with data reactions, so it accepts their properties too; model is the one that is refused rather than stored.
15 properties
- opstringRequired
  Comparison applied to the metric. Required on every monitor spec. instance_health requires GT.
  - Allowed values: GT, GEQ, LT, LEQ, EQ, NEQ
- thresholdnumberRequired
  Value compared against the metric. HTTP failure monitors count estimated 5xx responses in the selected window. Rate-based conditions use responses per second. dataset_refresh_errors counts refresh errors in the window. query_latency_p99 uses milliseconds. memory_working_set uses percent of the instance memory limit. A stored memory threshold above 1000 uses bytes. container_cpu uses percent of the defined CPU limit. dataset_status compares load-state numbers. instance_health requires 0. Every monitor spec requires a threshold.
- windowstring
  Range evaluated by query_failures, query_latency_p99, llm_failures, dataset_refresh_errors, http_5xx, flight_failures, and container_cpu. memory_working_set and dataset_status read the current value and ignore this field. instance_health reads current failure states and uses a fixed five-minute eviction observation window, independent of this field. Data reactions store this field but do not use it.
  - Allowed values: 1m, 5m, 15m, 30m, 1h
  - Default: 5m
- sustainSecsinteger
  Sustain delay in seconds. Failure monitors default to 0. Other monitors default to 300. Explicit values are preserved.
  - Minimum: 0
  - Maximum: 86400
- severitystring
  Severity the monitor fires at. Recorded on each monitor event and carried into the email or webhook notification.
  - Allowed values: warn, critical
  - Default: critical
- datasetstring
  Read by dataset_status, which watches this one dataset. Omit it to match any dataset in the project.
  - Minimum length: 1
  - Maximum length: 128
  - Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
- includeDetailsboolean
  When true, the recorded event and the notification may carry a details string quoted from the firing payload when it contains useful information. Off by default, because that payload may be sensitive. A notification's own summary, description, and observed value do not depend on it.
- valuestring | number
  Read by dataset_status for notification wording only, and only when threshold is not one of the state numbers above and this names a state. It never changes what the monitor evaluates. Otherwise a data-reaction property.
- columnstring
  A data-reaction property that no monitor evaluates. Leave it unset — a monitor carrying both column and dataset has its notification describe that row predicate instead of its own metric comparison.
  - Minimum length: 1
  - Maximum length: 64
  - Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
- datasetsarray of string
  A data-reaction property that no monitor reads.
  - Maximum items: 20
- conditionsarray of object
  A data-reaction property that no monitor evaluates. Leave it unset — a monitor carrying conditions has its notification describe them instead of its own metric comparison. IS_NULL and IS_NOT_NULL omit value.
  - Maximum items: 20
  4 properties
  - datasetstringRequired
    Minimum length: 1
    Maximum length: 128
    Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
  - columnstringRequired
    Minimum length: 1
    Maximum length: 64
    Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
  - opstringRequired
    Allowed values: EQ, NEQ, GT, GEQ, LT, LEQ, CONTAINS, STARTS_WITH, ENDS_WITH, IS_NULL, IS_NOT_NULL
  - valuestring | number
    Required except for IS_NULL and IS_NOT_NULL.
- returnFieldsarray of object
  Dataset fields returned by generated row-match queries. Include identity and all monitored fields.
  - Maximum items: 20
  2 properties
  - datasetstringRequired
  - columnsarray of stringRequired
    Minimum items: 1
    Maximum items: 1000
- queryLanguagestring
  A data-reaction property that no monitor reads.
  - Allowed values: cypher, gql
- querystring
  A data-reaction property that no monitor reads.
  - Maximum length: 10000
- modelobject
  Model transform. Data reactions only — sending it with a monitor template is refused with 400, not ignored.
  2 properties
  - modelstringRequired
    Minimum length: 1
    Maximum length: 128
  - instructionsstringRequired
    Minimum length: 1
    Maximum length: 4000
targetobject
Notification sink. Omit it to email the user the credential belongs to; a machine credential has no user, so its monitors email the organization owner.
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
Organization members to email, by user ID.
Maximum items: 50
emailsarray of string (email)
Maximum items: 20
type: httpobject
typestringRequired
Value: http
urlstring (uri)Required
The URL each notification is sent to, using method. Must be https and must resolve to a public address.
Minimum length: 1
Maximum length: 2048
methodstring
A create that omits it uses POST. An update that omits it keeps the stored method.
Allowed values: POST, PUT, PATCH
tokenstring
Bearer token sent with each delivery. Stored encrypted and never returned.
Minimum length: 1
Maximum length: 512
type: slackobject
typestringRequired
Value: slack
channelIdstringRequired
Slack conversation id. The organization must already have Slack connected.
Minimum length: 9
Maximum length: 32
Pattern: ^[CGD][A-Z0-9]{8,31}$
channelNamestring
Minimum length: 1
Maximum length: 80
targetsarray of object
Full destination set. When present, this replaces target and is the complete list. At most one sink of each type.
- Minimum items: 1
- Maximum items: 3
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
Organization members to email, by user ID.
Maximum items: 50
emailsarray of string (email)
Maximum items: 20
type: httpobject
typestringRequired
Value: http
urlstring (uri)Required
The URL each notification is sent to, using method. Must be https and must resolve to a public address.
Minimum length: 1
Maximum length: 2048
methodstring
A create that omits it uses POST. An update that omits it keeps the stored method.
Allowed values: POST, PUT, PATCH
tokenstring
Bearer token sent with each delivery. Stored encrypted and never returned.
Minimum length: 1
Maximum length: 512
type: slackobject
typestringRequired
Value: slack
channelIdstringRequired
Slack conversation id. The organization must already have Slack connected.
Minimum length: 9
Maximum length: 32
Pattern: ^[CGD][A-Z0-9]{8,31}$
channelNamestring
Minimum length: 1
Maximum length: 80
recipientUserIdsarray of integer
Legacy spelling of target.recipientUserIds, read only when an email target omits its own.
- Maximum items: 50

Responses

201Monitor createdapplication/json

A project monitor, as returned by the list, get, create and update operations. Every required property is always present; a nullable one carries null rather than being omitted. evaluation_unavailable_reason is present only when an Instance CPU monitor has lost its CPU limit. Fields not listed here are internal to the platform and are not part of the contract.

idstring (uuid)Required
Identifier of the monitor or reaction. This is the value the get, update and delete operations take.
org_idintegerRequired
Organization that owns the project
app_idintegerRequired
Project the monitor or reaction belongs to
created_byinteger | nullRequired
User who created it, when it was created by a user credential
namestringRequired
Display name, unique case-insensitively among the project's live monitors and data reactions
descriptionstring | nullRequired
kindstringRequired
The monitors endpoints only ever return runtime.
- Value: runtime
statusstringRequired
Whether it is evaluating
- Allowed values: active, disabled
template_idstringRequired
Template it was created from
specobjectRequired
Monitor parameters. Which properties are meaningful is decided by template_id. The create operation's request body lists the properties each template reads.
targetobjectRequired
The primary sink (email, then slack, then http). targets is the full list. An HTTP sink's token is write-only and is never returned.
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
emailsarray of string (email)
type: httpobject
typestringRequired
Value: http
urlstring (uri) | ""Required
The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
methodstring
Allowed values: POST, PUT, PATCH
type: slackobject
typestringRequired
Value: slack
channelIdstring | ""Required
The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
channelNamestring
Minimum length: 1
Maximum length: 80
targetsarray of objectRequired
Every configured sink, ordered email, then slack, then http. target is the first of these. An HTTP sink's token is never returned.
- Minimum items: 1
- Maximum items: 3
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
emailsarray of string (email)
type: httpobject
typestringRequired
Value: http
urlstring (uri) | ""Required
The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
methodstring
Allowed values: POST, PUT, PATCH
type: slackobject
typestringRequired
Value: slack
channelIdstring | ""Required
The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
channelNamestring
Minimum length: 1
Maximum length: 80
recipient_user_idsarray of integerRequired
Organization members emailed when the monitor fires. Empty when there is no email sink, and for an email sink addressed only by emails. When a created email sink named no recipients at all, the API stores the creating user; a machine credential has no user, so it stores none and the monitor emails the organization owner.
last_fired_atstring (date-time) | nullRequired
When it last fired, or null if it never has
last_resolved_atstring (date-time) | nullRequired
When it last resolved, or null if it never has
created_atstring (date-time)Required
updated_atstring (date-time)Required
evaluation_unavailable_reasonstring
Present when an existing Instance CPU monitor cannot evaluate because its CPU limit was removed.
- Value: cpu_limit_missing

400Invalid request body or project ID

401Unauthorized

403Insufficient scope

404Not Found

Project not found, or the template is not available for this project (code is monitor_template_unavailable). Monitors run only on managed projects, and only released templates are available unless the organization has early access.

409A live monitor or data reaction in this project already has this name

413Request body too large

422Slack is not connected for the organization

500Internal server error

502Failed to provision monitor

curl -X POST "https://api.spice.ai/v1/projects/<projectId>/monitors" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "templateId": "query_failures",
    "spec": {
      "op": "GT",
      "threshold": 0
    }
  }'

POST /v1/projects/<projectId>/monitors HTTP/1.1
Host: api.spice.ai
Authorization: Bearer <token>
Content-Type: application/json
Content-Length: 108

{
  "name": "string",
  "templateId": "query_failures",
  "spec": {
    "op": "GT",
    "threshold": 0
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "org_id": 0,
  "app_id": 0,
  "created_by": 0,
  "name": "string",
  "description": "string",
  "kind": "runtime",
  "status": "active",
  "template_id": "string",
  "spec": {},
  "target": {
    "type": "email",
    "recipientUserIds": [
      0
    ],
    "emails": [
      "user@example.com"
    ]
  },
  "targets": [
    {
      "type": "email",
      "recipientUserIds": [
        0
      ],
      "emails": [
        "user@example.com"
      ]
    }
  ],
  "recipient_user_ids": [
    0
  ],
  "last_fired_at": "2026-01-01T00:00:00Z",
  "last_resolved_at": "2026-01-01T00:00:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "evaluation_unavailable_reason": "cpu_limit_missing"
}

application/json

POST`https://api.spice.ai/v1/orgs/{orgId}/projects/{projectId}/monitors`

The org is orgId in the path. Creates a project monitor from a runtime template. Requires monitors:write. A monitor evaluates a runtime metric on a schedule and fires when the comparison holds; to fire on matching dataset rows instead, create a data reaction at /v1/projects/{projectId}/reactions.

Authorizations

AuthorizationstringRequired
Bearer <token>. Authentication lists the tokens it accepts.

Path parameters

orgIdintegerRequired
The org id from GET /v1/orgs
- Minimum: 1
projectIdintegerRequired
The ID of the project

Header parameters

X-Org-Namestring
When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400).
- Pattern: ^[A-Za-z0-9._-]{1,255}$

Body

application/jsonRequired

namestringRequired
Display name. Unique, case-insensitively, among the project's live monitors and data reactions — a collision answers 409.
- Minimum length: 1
- Maximum length: 100
descriptionstring
- Maximum length: 500
kindstring
Optional assertion that templateId names a monitor. A value that disagrees with the template is refused rather than ignored; omit it and the template decides.
- Value: runtime
templateIdstringRequired
The runtime template the monitor evaluates. query_latency_p95 is retained for existing monitors but cannot be used to create new ones; use query_latency_p99. container_cpu is available only on managed projects with a defined CPU limit. A data-reaction template is refused here — create those at /v1/projects/{projectId}/reactions.
- Allowed values: query_failures, query_latency_p95, query_latency_p99, llm_failures, dataset_refresh_errors, http_5xx, flight_failures, memory_working_set, container_cpu, dataset_status, instance_health
specobjectRequired
Monitor parameters. Which properties apply is decided by templateId — each property below names the templates that read it, and a property no monitor template reads is stored rather than rejected. spec is shared with data reactions, so it accepts their properties too; model is the one that is refused rather than stored.
15 properties
- opstringRequired
  Comparison applied to the metric. Required on every monitor spec. instance_health requires GT.
  - Allowed values: GT, GEQ, LT, LEQ, EQ, NEQ
- thresholdnumberRequired
  Value compared against the metric. HTTP failure monitors count estimated 5xx responses in the selected window. Rate-based conditions use responses per second. dataset_refresh_errors counts refresh errors in the window. query_latency_p99 uses milliseconds. memory_working_set uses percent of the instance memory limit. A stored memory threshold above 1000 uses bytes. container_cpu uses percent of the defined CPU limit. dataset_status compares load-state numbers. instance_health requires 0. Every monitor spec requires a threshold.
- windowstring
  Range evaluated by query_failures, query_latency_p99, llm_failures, dataset_refresh_errors, http_5xx, flight_failures, and container_cpu. memory_working_set and dataset_status read the current value and ignore this field. instance_health reads current failure states and uses a fixed five-minute eviction observation window, independent of this field. Data reactions store this field but do not use it.
  - Allowed values: 1m, 5m, 15m, 30m, 1h
  - Default: 5m
- sustainSecsinteger
  Sustain delay in seconds. Failure monitors default to 0. Other monitors default to 300. Explicit values are preserved.
  - Minimum: 0
  - Maximum: 86400
- severitystring
  Severity the monitor fires at. Recorded on each monitor event and carried into the email or webhook notification.
  - Allowed values: warn, critical
  - Default: critical
- datasetstring
  Read by dataset_status, which watches this one dataset. Omit it to match any dataset in the project.
  - Minimum length: 1
  - Maximum length: 128
  - Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
- includeDetailsboolean
  When true, the recorded event and the notification may carry a details string quoted from the firing payload when it contains useful information. Off by default, because that payload may be sensitive. A notification's own summary, description, and observed value do not depend on it.
- valuestring | number
  Read by dataset_status for notification wording only, and only when threshold is not one of the state numbers above and this names a state. It never changes what the monitor evaluates. Otherwise a data-reaction property.
- columnstring
  A data-reaction property that no monitor evaluates. Leave it unset — a monitor carrying both column and dataset has its notification describe that row predicate instead of its own metric comparison.
  - Minimum length: 1
  - Maximum length: 64
  - Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
- datasetsarray of string
  A data-reaction property that no monitor reads.
  - Maximum items: 20
- conditionsarray of object
  A data-reaction property that no monitor evaluates. Leave it unset — a monitor carrying conditions has its notification describe them instead of its own metric comparison. IS_NULL and IS_NOT_NULL omit value.
  - Maximum items: 20
  4 properties
  - datasetstringRequired
    Minimum length: 1
    Maximum length: 128
    Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
  - columnstringRequired
    Minimum length: 1
    Maximum length: 64
    Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
  - opstringRequired
    Allowed values: EQ, NEQ, GT, GEQ, LT, LEQ, CONTAINS, STARTS_WITH, ENDS_WITH, IS_NULL, IS_NOT_NULL
  - valuestring | number
    Required except for IS_NULL and IS_NOT_NULL.
- returnFieldsarray of object
  Dataset fields returned by generated row-match queries. Include identity and all monitored fields.
  - Maximum items: 20
  2 properties
  - datasetstringRequired
  - columnsarray of stringRequired
    Minimum items: 1
    Maximum items: 1000
- queryLanguagestring
  A data-reaction property that no monitor reads.
  - Allowed values: cypher, gql
- querystring
  A data-reaction property that no monitor reads.
  - Maximum length: 10000
- modelobject
  Model transform. Data reactions only — sending it with a monitor template is refused with 400, not ignored.
  2 properties
  - modelstringRequired
    Minimum length: 1
    Maximum length: 128
  - instructionsstringRequired
    Minimum length: 1
    Maximum length: 4000
targetobject
Notification sink. Omit it to email the user the credential belongs to; a machine credential has no user, so its monitors email the organization owner.
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
Organization members to email, by user ID.
Maximum items: 50
emailsarray of string (email)
Maximum items: 20
type: httpobject
typestringRequired
Value: http
urlstring (uri)Required
The URL each notification is sent to, using method. Must be https and must resolve to a public address.
Minimum length: 1
Maximum length: 2048
methodstring
A create that omits it uses POST. An update that omits it keeps the stored method.
Allowed values: POST, PUT, PATCH
tokenstring
Bearer token sent with each delivery. Stored encrypted and never returned.
Minimum length: 1
Maximum length: 512
type: slackobject
typestringRequired
Value: slack
channelIdstringRequired
Slack conversation id. The organization must already have Slack connected.
Minimum length: 9
Maximum length: 32
Pattern: ^[CGD][A-Z0-9]{8,31}$
channelNamestring
Minimum length: 1
Maximum length: 80
targetsarray of object
Full destination set. When present, this replaces target and is the complete list. At most one sink of each type.
- Minimum items: 1
- Maximum items: 3
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
Organization members to email, by user ID.
Maximum items: 50
emailsarray of string (email)
Maximum items: 20
type: httpobject
typestringRequired
Value: http
urlstring (uri)Required
The URL each notification is sent to, using method. Must be https and must resolve to a public address.
Minimum length: 1
Maximum length: 2048
methodstring
A create that omits it uses POST. An update that omits it keeps the stored method.
Allowed values: POST, PUT, PATCH
tokenstring
Bearer token sent with each delivery. Stored encrypted and never returned.
Minimum length: 1
Maximum length: 512
type: slackobject
typestringRequired
Value: slack
channelIdstringRequired
Slack conversation id. The organization must already have Slack connected.
Minimum length: 9
Maximum length: 32
Pattern: ^[CGD][A-Z0-9]{8,31}$
channelNamestring
Minimum length: 1
Maximum length: 80
recipientUserIdsarray of integer
Legacy spelling of target.recipientUserIds, read only when an email target omits its own.
- Maximum items: 50

Responses

201Monitor createdapplication/json

idstring (uuid)Required
Identifier of the monitor or reaction. This is the value the get, update and delete operations take.
org_idintegerRequired
Organization that owns the project
app_idintegerRequired
Project the monitor or reaction belongs to
created_byinteger | nullRequired
User who created it, when it was created by a user credential
namestringRequired
Display name, unique case-insensitively among the project's live monitors and data reactions
descriptionstring | nullRequired
kindstringRequired
The monitors endpoints only ever return runtime.
- Value: runtime
statusstringRequired
Whether it is evaluating
- Allowed values: active, disabled
template_idstringRequired
Template it was created from
specobjectRequired
Monitor parameters. Which properties are meaningful is decided by template_id. The create operation's request body lists the properties each template reads.
targetobjectRequired
The primary sink (email, then slack, then http). targets is the full list. An HTTP sink's token is write-only and is never returned.
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
emailsarray of string (email)
type: httpobject
typestringRequired
Value: http
urlstring (uri) | ""Required
The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
methodstring
Allowed values: POST, PUT, PATCH
type: slackobject
typestringRequired
Value: slack
channelIdstring | ""Required
The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
channelNamestring
Minimum length: 1
Maximum length: 80
targetsarray of objectRequired
Every configured sink, ordered email, then slack, then http. target is the first of these. An HTTP sink's token is never returned.
- Minimum items: 1
- Maximum items: 3
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
emailsarray of string (email)
type: httpobject
typestringRequired
Value: http
urlstring (uri) | ""Required
The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
methodstring
Allowed values: POST, PUT, PATCH
type: slackobject
typestringRequired
Value: slack
channelIdstring | ""Required
The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
channelNamestring
Minimum length: 1
Maximum length: 80
recipient_user_idsarray of integerRequired
Organization members emailed when the monitor fires. Empty when there is no email sink, and for an email sink addressed only by emails. When a created email sink named no recipients at all, the API stores the creating user; a machine credential has no user, so it stores none and the monitor emails the organization owner.
last_fired_atstring (date-time) | nullRequired
When it last fired, or null if it never has
last_resolved_atstring (date-time) | nullRequired
When it last resolved, or null if it never has
created_atstring (date-time)Required
updated_atstring (date-time)Required
evaluation_unavailable_reasonstring
Present when an existing Instance CPU monitor cannot evaluate because its CPU limit was removed.
- Value: cpu_limit_missing

400Bad Request

Invalid request body or project ID. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).

401Unauthorized

403Forbidden

Insufficient scope. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).

404Not Found

409A live monitor or data reaction in this project already has this name

413Request body too large

422Slack is not connected for the organization

500Internal server error

502Failed to provision monitor

curl -X POST "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/monitors" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "templateId": "query_failures",
    "spec": {
      "op": "GT",
      "threshold": 0
    }
  }'

POST /v1/orgs/<orgId>/projects/<projectId>/monitors HTTP/1.1
Host: api.spice.ai
Authorization: Bearer <token>
Content-Type: application/json
Content-Length: 108

{
  "name": "string",
  "templateId": "query_failures",
  "spec": {
    "op": "GT",
    "threshold": 0
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "org_id": 0,
  "app_id": 0,
  "created_by": 0,
  "name": "string",
  "description": "string",
  "kind": "runtime",
  "status": "active",
  "template_id": "string",
  "spec": {},
  "target": {
    "type": "email",
    "recipientUserIds": [
      0
    ],
    "emails": [
      "user@example.com"
    ]
  },
  "targets": [
    {
      "type": "email",
      "recipientUserIds": [
        0
      ],
      "emails": [
        "user@example.com"
      ]
    }
  ],
  "recipient_user_ids": [
    0
  ],
  "last_fired_at": "2026-01-01T00:00:00Z",
  "last_resolved_at": "2026-01-01T00:00:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "evaluation_unavailable_reason": "cpu_limit_missing"
}

application/json

POST`https://api.spice.ai/v1/apps/{appId}/monitors`Deprecated

Legacy alias of /v1/projects/{projectId}/monitors — projects were previously called apps. Creates a project monitor from a runtime template. Requires monitors:write. A monitor evaluates a runtime metric on a schedule and fires when the comparison holds; to fire on matching dataset rows instead, create a data reaction at /v1/projects/{projectId}/reactions.

Authorizations

AuthorizationstringRequired
Bearer <token>. Authentication lists the tokens it accepts.

Path parameters

appIdintegerRequired
The ID of the project

Header parameters

X-Org-Namestring
The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own. A portal session token is bound to none, so it must send this header on every route but GET /v1/orgs (400 org_assertion_required otherwise).
- Pattern: ^[A-Za-z0-9._-]{1,255}$

Body

application/jsonRequired

namestringRequired
Display name. Unique, case-insensitively, among the project's live monitors and data reactions — a collision answers 409.
- Minimum length: 1
- Maximum length: 100
descriptionstring
- Maximum length: 500
kindstring
Optional assertion that templateId names a monitor. A value that disagrees with the template is refused rather than ignored; omit it and the template decides.
- Value: runtime
templateIdstringRequired
The runtime template the monitor evaluates. query_latency_p95 is retained for existing monitors but cannot be used to create new ones; use query_latency_p99. container_cpu is available only on managed projects with a defined CPU limit. A data-reaction template is refused here — create those at /v1/projects/{projectId}/reactions.
- Allowed values: query_failures, query_latency_p95, query_latency_p99, llm_failures, dataset_refresh_errors, http_5xx, flight_failures, memory_working_set, container_cpu, dataset_status, instance_health
specobjectRequired
Monitor parameters. Which properties apply is decided by templateId — each property below names the templates that read it, and a property no monitor template reads is stored rather than rejected. spec is shared with data reactions, so it accepts their properties too; model is the one that is refused rather than stored.
15 properties
- opstringRequired
  Comparison applied to the metric. Required on every monitor spec. instance_health requires GT.
  - Allowed values: GT, GEQ, LT, LEQ, EQ, NEQ
- thresholdnumberRequired
  Value compared against the metric. HTTP failure monitors count estimated 5xx responses in the selected window. Rate-based conditions use responses per second. dataset_refresh_errors counts refresh errors in the window. query_latency_p99 uses milliseconds. memory_working_set uses percent of the instance memory limit. A stored memory threshold above 1000 uses bytes. container_cpu uses percent of the defined CPU limit. dataset_status compares load-state numbers. instance_health requires 0. Every monitor spec requires a threshold.
- windowstring
  Range evaluated by query_failures, query_latency_p99, llm_failures, dataset_refresh_errors, http_5xx, flight_failures, and container_cpu. memory_working_set and dataset_status read the current value and ignore this field. instance_health reads current failure states and uses a fixed five-minute eviction observation window, independent of this field. Data reactions store this field but do not use it.
  - Allowed values: 1m, 5m, 15m, 30m, 1h
  - Default: 5m
- sustainSecsinteger
  Sustain delay in seconds. Failure monitors default to 0. Other monitors default to 300. Explicit values are preserved.
  - Minimum: 0
  - Maximum: 86400
- severitystring
  Severity the monitor fires at. Recorded on each monitor event and carried into the email or webhook notification.
  - Allowed values: warn, critical
  - Default: critical
- datasetstring
  Read by dataset_status, which watches this one dataset. Omit it to match any dataset in the project.
  - Minimum length: 1
  - Maximum length: 128
  - Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
- includeDetailsboolean
  When true, the recorded event and the notification may carry a details string quoted from the firing payload when it contains useful information. Off by default, because that payload may be sensitive. A notification's own summary, description, and observed value do not depend on it.
- valuestring | number
  Read by dataset_status for notification wording only, and only when threshold is not one of the state numbers above and this names a state. It never changes what the monitor evaluates. Otherwise a data-reaction property.
- columnstring
  A data-reaction property that no monitor evaluates. Leave it unset — a monitor carrying both column and dataset has its notification describe that row predicate instead of its own metric comparison.
  - Minimum length: 1
  - Maximum length: 64
  - Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
- datasetsarray of string
  A data-reaction property that no monitor reads.
  - Maximum items: 20
- conditionsarray of object
  A data-reaction property that no monitor evaluates. Leave it unset — a monitor carrying conditions has its notification describe them instead of its own metric comparison. IS_NULL and IS_NOT_NULL omit value.
  - Maximum items: 20
  4 properties
  - datasetstringRequired
    Minimum length: 1
    Maximum length: 128
    Pattern: ^(?!.*\.\.)[A-Za-z_][A-Za-z0-9_.-]*$
  - columnstringRequired
    Minimum length: 1
    Maximum length: 64
    Pattern: ^[A-Za-z_][A-Za-z0-9_]*$
  - opstringRequired
    Allowed values: EQ, NEQ, GT, GEQ, LT, LEQ, CONTAINS, STARTS_WITH, ENDS_WITH, IS_NULL, IS_NOT_NULL
  - valuestring | number
    Required except for IS_NULL and IS_NOT_NULL.
- returnFieldsarray of object
  Dataset fields returned by generated row-match queries. Include identity and all monitored fields.
  - Maximum items: 20
  2 properties
  - datasetstringRequired
  - columnsarray of stringRequired
    Minimum items: 1
    Maximum items: 1000
- queryLanguagestring
  A data-reaction property that no monitor reads.
  - Allowed values: cypher, gql
- querystring
  A data-reaction property that no monitor reads.
  - Maximum length: 10000
- modelobject
  Model transform. Data reactions only — sending it with a monitor template is refused with 400, not ignored.
  2 properties
  - modelstringRequired
    Minimum length: 1
    Maximum length: 128
  - instructionsstringRequired
    Minimum length: 1
    Maximum length: 4000
targetobject
Notification sink. Omit it to email the user the credential belongs to; a machine credential has no user, so its monitors email the organization owner.
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
Organization members to email, by user ID.
Maximum items: 50
emailsarray of string (email)
Maximum items: 20
type: httpobject
typestringRequired
Value: http
urlstring (uri)Required
The URL each notification is sent to, using method. Must be https and must resolve to a public address.
Minimum length: 1
Maximum length: 2048
methodstring
A create that omits it uses POST. An update that omits it keeps the stored method.
Allowed values: POST, PUT, PATCH
tokenstring
Bearer token sent with each delivery. Stored encrypted and never returned.
Minimum length: 1
Maximum length: 512
type: slackobject
typestringRequired
Value: slack
channelIdstringRequired
Slack conversation id. The organization must already have Slack connected.
Minimum length: 9
Maximum length: 32
Pattern: ^[CGD][A-Z0-9]{8,31}$
channelNamestring
Minimum length: 1
Maximum length: 80
targetsarray of object
Full destination set. When present, this replaces target and is the complete list. At most one sink of each type.
- Minimum items: 1
- Maximum items: 3
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
Organization members to email, by user ID.
Maximum items: 50
emailsarray of string (email)
Maximum items: 20
type: httpobject
typestringRequired
Value: http
urlstring (uri)Required
The URL each notification is sent to, using method. Must be https and must resolve to a public address.
Minimum length: 1
Maximum length: 2048
methodstring
A create that omits it uses POST. An update that omits it keeps the stored method.
Allowed values: POST, PUT, PATCH
tokenstring
Bearer token sent with each delivery. Stored encrypted and never returned.
Minimum length: 1
Maximum length: 512
type: slackobject
typestringRequired
Value: slack
channelIdstringRequired
Slack conversation id. The organization must already have Slack connected.
Minimum length: 9
Maximum length: 32
Pattern: ^[CGD][A-Z0-9]{8,31}$
channelNamestring
Minimum length: 1
Maximum length: 80
recipientUserIdsarray of integer
Legacy spelling of target.recipientUserIds, read only when an email target omits its own.
- Maximum items: 50

Responses

201Monitor createdapplication/json

idstring (uuid)Required
Identifier of the monitor or reaction. This is the value the get, update and delete operations take.
org_idintegerRequired
Organization that owns the project
app_idintegerRequired
Project the monitor or reaction belongs to
created_byinteger | nullRequired
User who created it, when it was created by a user credential
namestringRequired
Display name, unique case-insensitively among the project's live monitors and data reactions
descriptionstring | nullRequired
kindstringRequired
The monitors endpoints only ever return runtime.
- Value: runtime
statusstringRequired
Whether it is evaluating
- Allowed values: active, disabled
template_idstringRequired
Template it was created from
specobjectRequired
Monitor parameters. Which properties are meaningful is decided by template_id. The create operation's request body lists the properties each template reads.
targetobjectRequired
The primary sink (email, then slack, then http). targets is the full list. An HTTP sink's token is write-only and is never returned.
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
emailsarray of string (email)
type: httpobject
typestringRequired
Value: http
urlstring (uri) | ""Required
The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
methodstring
Allowed values: POST, PUT, PATCH
type: slackobject
typestringRequired
Value: slack
channelIdstring | ""Required
The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
channelNamestring
Minimum length: 1
Maximum length: 80
targetsarray of objectRequired
Every configured sink, ordered email, then slack, then http. target is the first of these. An HTTP sink's token is never returned.
- Minimum items: 1
- Maximum items: 3
3 options
One of
type: emailobject
typestringRequired
Value: email
recipientUserIdsarray of integer
emailsarray of string (email)
type: httpobject
typestringRequired
Value: http
urlstring (uri) | ""Required
The sink's URL. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
methodstring
Allowed values: POST, PUT, PATCH
type: slackobject
typestringRequired
Value: slack
channelIdstring | ""Required
The Slack channel ID. An empty string means the stored sink no longer passes validation. Update the sink to replace it.
channelNamestring
Minimum length: 1
Maximum length: 80
recipient_user_idsarray of integerRequired
Organization members emailed when the monitor fires. Empty when there is no email sink, and for an email sink addressed only by emails. When a created email sink named no recipients at all, the API stores the creating user; a machine credential has no user, so it stores none and the monitor emails the organization owner.
last_fired_atstring (date-time) | nullRequired
When it last fired, or null if it never has
last_resolved_atstring (date-time) | nullRequired
When it last resolved, or null if it never has
created_atstring (date-time)Required
updated_atstring (date-time)Required
evaluation_unavailable_reasonstring
Present when an existing Instance CPU monitor cannot evaluate because its CPU limit was removed.
- Value: cpu_limit_missing

400Invalid request body or project ID

401Unauthorized

403Insufficient scope

404Not Found

409A live monitor or data reaction in this project already has this name

413Request body too large

422Slack is not connected for the organization

500Internal server error

502Failed to provision monitor

OpenAPIapi.spice.ai/openapi.json

curl -X POST "https://api.spice.ai/v1/apps/<appId>/monitors" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "templateId": "query_failures",
    "spec": {
      "op": "GT",
      "threshold": 0
    }
  }'

POST /v1/apps/<appId>/monitors HTTP/1.1
Host: api.spice.ai
Authorization: Bearer <token>
Content-Type: application/json
Content-Length: 108

{
  "name": "string",
  "templateId": "query_failures",
  "spec": {
    "op": "GT",
    "threshold": 0
  }
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "org_id": 0,
  "app_id": 0,
  "created_by": 0,
  "name": "string",
  "description": "string",
  "kind": "runtime",
  "status": "active",
  "template_id": "string",
  "spec": {},
  "target": {
    "type": "email",
    "recipientUserIds": [
      0
    ],
    "emails": [
      "user@example.com"
    ]
  },
  "targets": [
    {
      "type": "email",
      "recipientUserIds": [
        0
      ],
      "emails": [
        "user@example.com"
      ]
    }
  ],
  "recipient_user_ids": [
    0
  ],
  "last_fired_at": "2026-01-01T00:00:00Z",
  "last_resolved_at": "2026-01-01T00:00:00Z",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z",
  "evaluation_unavailable_reason": "cpu_limit_missing"
}

application/json

POSThttps://api.spice.ai/v1/projects/{projectId}/monitors

Authorizations

Path parameters

Header parameters

Body

Responses

POSThttps://api.spice.ai/v1/orgs/{orgId}/projects/{projectId}/monitors

Authorizations

Path parameters

Header parameters

Body

Responses

POSThttps://api.spice.ai/v1/apps/{appId}/monitorsDeprecated

Authorizations

Path parameters

Header parameters

Body

Responses

POST`https://api.spice.ai/v1/projects/{projectId}/monitors`

POST`https://api.spice.ai/v1/orgs/{orgId}/projects/{projectId}/monitors`

POST`https://api.spice.ai/v1/apps/{appId}/monitors`Deprecated