SPspice
Monitors

Create a project monitor

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.

post/v1/apps/{appId}/monitors

Request

  • Base URL
    https://api.spice.ai
  • Auth
    HTTP bearer

Path parameters

appIdinteger required

The ID of the project

Headers

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).

Request body

namestring required

Display name. Unique, case-insensitively, among the project's live monitors and data reactions. A collision answers 409.

descriptionstring
kind'runtime'

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.

templateId'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' required

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.

recipientUserIdsinteger[]

Legacy spelling of target.recipientUserIds, read only when an email target omits its own.

Response

Monitor created

idstring uuid required

Identifier of the monitor or reaction. This is the value the get, update and delete operations take.

org_idinteger required

Organization that owns the project

app_idinteger required

Project the monitor or reaction belongs to

created_byinteger nullable required

User who created it, when it was created by a user credential

namestring required

Display name, unique case-insensitively among the project's live monitors and data reactions

descriptionstring nullable required
kind'runtime' required

The monitors endpoints only ever return runtime.

status'active' | 'disabled' required

Whether it is evaluating

template_idstring required

Template it was created from

specobject required

Monitor parameters. Which properties are meaningful is decided by template_id. The create operation's request body lists the properties each template reads.

recipient_user_idsinteger[] required

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 nullable required

When it last fired, or null if it never has

last_resolved_atstring date-time nullable required

When it last resolved, or null if it never has

created_atstring date-time required
updated_atstring date-time required
evaluation_unavailable_reason'cpu_limit_missing'

Present when an existing Instance CPU monitor cannot evaluate because its CPU limit was removed.

Changes

No recorded changes to this operation across all 1 revision of this API.