Management APIs / Monitors

Get a project monitor

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

Returns a single project monitor. Requires monitors:read. An existing container_cpu monitor without an effective CPU limit remains visible with evaluation_unavailable_reason set to cpu_limit_missing.

Authorizations

  • AuthorizationstringRequired

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

Path parameters

  • projectIdintegerRequired

  • alertIdstring (uuid)Required

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}$

Responses

200Monitorapplication/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 project or monitor ID

401Unauthorized

403Insufficient scope

404Project or monitor not found

500Internal server error

curl "https://api.spice.ai/v1/projects/<projectId>/monitors/<alertId>" \
  -H "Authorization: Bearer <token>"
{
  "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

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

The org is orgId in the path. Returns a single project monitor. Requires monitors:read. An existing container_cpu monitor without an effective CPU limit remains visible with evaluation_unavailable_reason set to cpu_limit_missing.

Authorizations

  • AuthorizationstringRequired

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

Path parameters

  • orgIdintegerRequired

    The org id from GET /v1/orgs

    • Minimum: 1

  • projectIdintegerRequired

  • alertIdstring (uuid)Required

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}$

Responses

200Monitorapplication/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
400Bad Request

Invalid project or monitor 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).

404Project or monitor not found

500Internal server error

curl "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/monitors/<alertId>" \
  -H "Authorization: Bearer <token>"
{
  "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

GEThttps://api.spice.ai/v1/apps/{appId}/monitors/{alertId}Deprecated

Legacy alias of /v1/projects/{projectId}/monitors/{alertId} — projects were previously called apps. Returns a single project monitor. Requires monitors:read. An existing container_cpu monitor without an effective CPU limit remains visible with evaluation_unavailable_reason set to cpu_limit_missing.

Authorizations

  • AuthorizationstringRequired

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

Path parameters

  • appIdintegerRequired

  • alertIdstring (uuid)Required

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}$

Responses

200Monitorapplication/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 project or monitor ID

401Unauthorized

403Insufficient scope

404Project or monitor not found

500Internal server error

OpenAPIapi.spice.ai/openapi.json

curl "https://api.spice.ai/v1/apps/<appId>/monitors/<alertId>" \
  -H "Authorization: Bearer <token>"
{
  "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