> ## Documentation Index > Fetch the complete documentation index at: https://docs.use.observer/llms.txt > Use this file to discover all available pages before exploring further. # Test a probe > A key with write:metrics or write:config may call it. Validates source_config with the same rules as a metric write, then runs the probe once: on the given agent (on its network, with its env-var secrets), or, with no agent_id, from Observer's cloud for a public HTTP check. Waits up to wait_seconds (default 20) for the agent; if it has not answered by then the response is 202 with a job to poll via getProbeTest. Nothing is stored: no metric, no sample, no status change. The result carries only the value, its unit, the status the given thresholds would produce, a reason code and the duration; never response bodies, rows or headers. Value units by source_type: - prometheus: Value: scalar result of the PromQL query, as returned by the query; Observer does not rescale it. - http: Value: ms: response time in milliseconds. With json_path set: the number extracted from the JSON response at json_path (booleans read as 1/0); unit as in the response. - tcp: Value: ms: TCP connect time in milliseconds. - dns: Value: ms: DNS resolve time in milliseconds. - icmp: Value by interpretation: interpretation=latency (default) → ms: average round-trip time in milliseconds; interpretation=packet_loss → %: percentage of pings lost, 0 to 100; interpretation=reachability → 1 when any ping returned, 0 when none did. - tls_cert: Value: days: days until the certificate expires. - grpc: Value by interpretation: interpretation=health_state (default) → 1 when the health check reports SERVING, 0 when NOT_SERVING; interpretation=latency → ms: health check round-trip time in milliseconds. - websocket: Value by interpretation: interpretation=handshake_latency (default) → ms: handshake time in milliseconds; interpretation=round_trip_latency → ms: message round-trip time in milliseconds; interpretation=connection_success → 1 when the socket opened, 0 when it did not. - mtls_http: Value: ms: response time in milliseconds (deprecated alias of http). With json_path set: the number extracted from the JSON response at json_path (booleans read as 1/0); unit as in the response. - database: Value: scalar returned by the read-only query (one row, one column), as returned by the query; Observer does not rescale it. - otlp: Value: aggregated value of the pushed OTLP data points, in the instrument's own unit. - cloudwatch: Value: latest CloudWatch datapoint for the chosen statistic, in the metric's CloudWatch unit. - custom: Value: number returned by the registered probe function, in whatever unit it uses. - loki: Value: scalar result of the LogQL aggregation, as returned by the query; Observer does not rescale it. - elasticsearch: Value: value of the named aggregation, as returned by the query; Observer does not rescale it. - host: Value by metric: metric=cpu (default) → %: CPU utilisation percentage, 0 to 100; metric=memory → %: used memory percentage, 0 to 100; metric=filesystem → %: used disk space percentage of the mountpoint, 0 to 100; metric=network → B/s: network throughput in bytes per second (received + sent); metric=load → 1-minute load average divided by the CPU count. - manual: Value: no measured value; the status is set by hand or by an open incident. - heartbeat: Value: s: seconds since the last successful ping. - alert: Value: worst firing alert as a score: 0 none, 1 degraded, 2 unhealthy. ## OpenAPI ````yaml api-reference/openapi.json POST /metrics/test openapi: 3.1.0 info: title: Observer API version: 1.0.0 description: >- Public API for Observer: read services, metrics, SLOs and SLA statements; manage incidents, maintenance windows, manual metric status, config as code and Observer Agents. Bearer-auth via API keys (obs_pub_…), scoped per key. RFC 7807 problem-detail errors. Cursor pagination. Rate limits are per organization. Every date-time value is RFC 3339 in UTC with millisecond precision (`2026-01-31T12:00:00.000Z`). servers: - url: https://use.observer/api/v1 security: - bearerAuth: [] paths: /metrics/test: post: tags: - metrics summary: >- Run a draft probe once and return the value it measures, without creating a metric description: >- A key with write:metrics or write:config may call it. Validates source_config with the same rules as a metric write, then runs the probe once: on the given agent (on its network, with its env-var secrets), or, with no agent_id, from Observer's cloud for a public HTTP check. Waits up to wait_seconds (default 20) for the agent; if it has not answered by then the response is 202 with a job to poll via getProbeTest. Nothing is stored: no metric, no sample, no status change. The result carries only the value, its unit, the status the given thresholds would produce, a reason code and the duration; never response bodies, rows or headers. Value units by source_type: - prometheus: Value: scalar result of the PromQL query, as returned by the query; Observer does not rescale it. - http: Value: ms: response time in milliseconds. With json_path set: the number extracted from the JSON response at json_path (booleans read as 1/0); unit as in the response. - tcp: Value: ms: TCP connect time in milliseconds. - dns: Value: ms: DNS resolve time in milliseconds. - icmp: Value by interpretation: interpretation=latency (default) → ms: average round-trip time in milliseconds; interpretation=packet_loss → %: percentage of pings lost, 0 to 100; interpretation=reachability → 1 when any ping returned, 0 when none did. - tls_cert: Value: days: days until the certificate expires. - grpc: Value by interpretation: interpretation=health_state (default) → 1 when the health check reports SERVING, 0 when NOT_SERVING; interpretation=latency → ms: health check round-trip time in milliseconds. - websocket: Value by interpretation: interpretation=handshake_latency (default) → ms: handshake time in milliseconds; interpretation=round_trip_latency → ms: message round-trip time in milliseconds; interpretation=connection_success → 1 when the socket opened, 0 when it did not. - mtls_http: Value: ms: response time in milliseconds (deprecated alias of http). With json_path set: the number extracted from the JSON response at json_path (booleans read as 1/0); unit as in the response. - database: Value: scalar returned by the read-only query (one row, one column), as returned by the query; Observer does not rescale it. - otlp: Value: aggregated value of the pushed OTLP data points, in the instrument's own unit. - cloudwatch: Value: latest CloudWatch datapoint for the chosen statistic, in the metric's CloudWatch unit. - custom: Value: number returned by the registered probe function, in whatever unit it uses. - loki: Value: scalar result of the LogQL aggregation, as returned by the query; Observer does not rescale it. - elasticsearch: Value: value of the named aggregation, as returned by the query; Observer does not rescale it. - host: Value by metric: metric=cpu (default) → %: CPU utilisation percentage, 0 to 100; metric=memory → %: used memory percentage, 0 to 100; metric=filesystem → %: used disk space percentage of the mountpoint, 0 to 100; metric=network → B/s: network throughput in bytes per second (received + sent); metric=load → 1-minute load average divided by the CPU count. - manual: Value: no measured value; the status is set by hand or by an open incident. - heartbeat: Value: s: seconds since the last successful ping. - alert: Value: worst firing alert as a score: 0 none, 1 degraded, 2 unhealthy. operationId: testProbe requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProbeTestRequest' responses: '200': description: the probe ran content: application/json: schema: $ref: '#/components/schemas/ProbeTestResult' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-RateLimit-Daily-Limit: $ref: '#/components/headers/X-RateLimit-Daily-Limit' X-RateLimit-Daily-Remaining: $ref: '#/components/headers/X-RateLimit-Daily-Remaining' X-RateLimit-Daily-Reset: $ref: '#/components/headers/X-RateLimit-Daily-Reset' '202': description: the agent has not answered yet; poll getProbeTest content: application/json: schema: $ref: '#/components/schemas/ProbeTestPending' headers: X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-RateLimit-Daily-Limit: $ref: '#/components/headers/X-RateLimit-Daily-Limit' X-RateLimit-Daily-Remaining: $ref: '#/components/headers/X-RateLimit-Daily-Remaining' X-RateLimit-Daily-Reset: $ref: '#/components/headers/X-RateLimit-Daily-Reset' '400': description: >- `invalid_json`: the body is not a JSON object. `invalid_agent_id`: not a uuid. `invalid_source_type` / `unsupported_source_type`: missing, or a type that cannot be tested. `invalid_probe_config`: source_config does not validate (`errors` lists each problem). `invalid_thresholds`, `invalid_wait_seconds`: out of shape or range. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': description: >- `unauthenticated`: no bearer token was sent, or the key is invalid or revoked. `detail` distinguishes the two. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '403': description: >- `forbidden`: the key holds neither `write:metrics` nor `write:config`. `plan_does_not_permit_api`: the plan does not include the public API. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '404': description: '`agent_not_found`: no agent with that id in this organization.' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '409': description: >- `agent_unavailable`: no agent can run it now. `reason` says why: no_agent (pass agent_id), offline, never_connected, outdated (below `min_agent_version`), revoked; `private_url: true` when the cloud refused a non-public URL. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': description: >- `rate_limited`: the organization's API limit, or the probe-test limit (30 agent tests or 20 cloud tests a minute), is used up; `Retry-After` says when to retry. `queue_full`: the agent already has 20 jobs waiting; `Retry-After` and `retry_after` say when to retry. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' headers: Retry-After: $ref: '#/components/headers/Retry-After' X-RateLimit-Limit: $ref: '#/components/headers/X-RateLimit-Limit' X-RateLimit-Remaining: $ref: '#/components/headers/X-RateLimit-Remaining' X-RateLimit-Reset: $ref: '#/components/headers/X-RateLimit-Reset' X-RateLimit-Daily-Limit: $ref: '#/components/headers/X-RateLimit-Daily-Limit' X-RateLimit-Daily-Remaining: $ref: '#/components/headers/X-RateLimit-Daily-Remaining' X-RateLimit-Daily-Reset: $ref: '#/components/headers/X-RateLimit-Daily-Reset' '500': description: '`internal_error`: an unhandled server error. Safe to retry.' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '502': description: >- `probe_test_failed`: the agent could not run the test (`reason` is its error code). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '504': description: '`probe_test_expired`: the agent did not answer within 2 minutes.' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' security: - bearerAuth: - write:metrics - bearerAuth: - write:config components: schemas: ProbeTestRequest: type: object required: - source_type - source_config properties: agent_id: type: - string - 'null' format: uuid description: >- The Observer Agent to run the test on (listAgents). It must be online and run agent 1.7.0 or later. Omit it to test a public HTTP check from Observer's cloud instead (header_refs secrets are not sent then); every other source type needs an agent. source_type: type: string enum: - prometheus - http - tcp - dns - icmp - tls_cert - grpc - websocket - mtls_http - database - cloudwatch - loki - elasticsearch - host description: >- The probe type. custom, otlp (push), manual, heartbeat and alert cannot be tested. source_config: type: object additionalProperties: true description: >- The same object a metric's source_config takes for this source_type (see the SourceConfig schemas used by applyConfig); validated the same way before anything runs. thresholds: type: object description: >- Optional. With all four set, `status` says what the metric's status would be. Strict comparisons: over is >, under is <, equal is =. properties: healthy_operation: type: string enum: - over - under - equal healthy_value: type: number unhealthy_operation: type: string enum: - over - under - equal unhealthy_value: type: number wait_seconds: type: integer minimum: 0 maximum: 20 default: 20 description: >- How long to wait for the agent's answer before returning 202 with a job to poll. Cloud tests always answer at once. ProbeTestResult: type: object required: - value - unit - status - duration_ms - mode properties: value: type: - number - 'null' description: >- What the probe measured, in `unit`. null when it got no value (see reason). unit: type: - string - 'null' description: >- Unit of value (ms, %, days, s, B/s), or null for a bare number. Same rules as a metric's unit. value_description: type: - string - 'null' description: What the value is, in words. status: type: - string - 'null' enum: - healthy - degraded - unhealthy - no_data - null description: >- The status these thresholds give the value; no_data when the probe got no value. null when a value was measured but thresholds were not all given. reason: type: - string - 'null' description: >- Why there is no value: the agent's reason code (e.g. ETIMEDOUT, unexpected_status:503). null on success. reason_label: type: - string - 'null' description: Short human description of `reason`. reason_hint: type: - string - 'null' description: What usually causes `reason` and how to fix it. duration_ms: type: integer description: How long the probe took, in milliseconds. mode: type: string enum: - agent - cloud description: >- agent: ran on the agent's network with its secrets. cloud: a public HTTP check run from Observer's cloud. job_id: type: - string - 'null' format: uuid description: The agent job (agent mode only). agent_id: type: - string - 'null' format: uuid thresholds_complete: type: boolean skipped_secret_headers: type: array items: type: string description: >- Cloud mode only: header_refs names that were not sent, because their values live on an agent host. ProbeTestPending: type: object required: - job_id - status - poll properties: job_id: type: string format: uuid status: type: string enum: - pending - running agent_id: type: string format: uuid expires_at: type: string format: date-time description: The agent must answer by then (2 minutes after the POST). poll: type: string description: Path to GET for the result (getProbeTest). detail: type: string Problem: type: object required: - type - title - status example: type: https://docs.use.observer/api/getting-started/errors#forbidden title: forbidden status: 403 detail: 'missing scope: write:incidents' properties: type: type: string format: uri description: Errors reference URI with the title token as the fragment. example: https://docs.use.observer/api/getting-started/errors#forbidden title: type: string description: Stable error token. Branch on this, not on detail. status: type: integer detail: type: string description: Human-readable explanation. Wording may change. retry_after: type: integer description: >- 429 only: seconds until the exhausted window resets (mirrors Retry-After). limit: type: object description: '429 only: which organization limit was hit.' properties: scope: type: string enum: - organization window: type: string enum: - minute - day max: type: integer plan: type: string errors: type: array description: >- Validation failures (config_invalid, invalid_customer_targeting): one entry per problem. items: type: object properties: path: type: string message: type: string warnings: type: array description: >- config_invalid only: the same non-fatal warnings a successful apply returns. items: type: object properties: path: type: string message: type: string unknown_customers: type: array description: >- unknown_customers only: the submitted values that matched no customer in your organization. items: type: string unknown_services: type: array description: >- unknown_services only: the submitted `affected_services` values that matched no service in your organization. items: {} referenced_by: type: object description: >- in_use only: what depends on the object (slos, pages: lists of { id, config_key, name }; subscribers: a count). quota: type: object description: >- quota_exceeded / feature_locked on a create, item_suspended_plan on a write to a suspended item: the plan limit involved. properties: capability: type: string used: type: - integer - 'null' cap: type: - integer - 'null' plan: type: - string - 'null' upgrade: type: object description: >- Plan-limit problems only, when a higher plan lifts the limit: the smallest such plan and the pricing page. properties: plan: type: string label: type: string url: type: string format: uri headers: X-RateLimit-Limit: description: Requests allowed per minute for the organization. schema: type: integer X-RateLimit-Remaining: description: Requests left in the current minute. schema: type: integer X-RateLimit-Reset: description: Seconds until the per-minute window resets. schema: type: integer X-RateLimit-Daily-Limit: description: Requests allowed per UTC day for the organization. schema: type: integer X-RateLimit-Daily-Remaining: description: Requests left today (UTC). schema: type: integer X-RateLimit-Daily-Reset: description: Seconds until the daily quota resets (UTC midnight). schema: type: integer Retry-After: description: '429 only: seconds to wait before retrying.' schema: type: integer securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: obs_pub_ description: >- An organization API key (obs_pub_…) sent as `Authorization: Bearer `. Each key carries scopes; an endpoint lists the scope it needs. `read:change_events` is reserved: keys can carry it, but no endpoint needs it yet. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.