---
# @generated by sylphx-gen. Do not edit.
title: "Probe a service observation"
description: "`hosting.service_observations.probe` (POST /v1/{name}:probe): Performs one safe same-environment transport observation."
type: reference
product: hosting
summary: "Performs one safe same-environment transport observation."
updated: 2026-09-28
nav: false
---

Performs one safe same-environment transport observation. Unlike a readiness read, this explicitly requested HTTP instrument may activate an idle service. No caller credential is forwarded to the workload.

- **Path** `POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/service_observations/service-observation:probe`
- **Scope** `hosting:read`
- **Effect** `read` — nothing is written.
- **Collection** [service_observations](/docs/api/service_observations)

## Request

| Field | Type | What it is |
| --- | --- | --- |
| `name` | `string` | Same-environment service observation name. Required. |
| `method` | `string` | GET or HEAD; defaults to HEAD. |
| `path` | `string` | Canonical safe path; defaults to /healthz. |
| `expect_status` | `uint32[]` | Allowed statuses; defaults to 200 through 299. |
| `expect_body` | `string` | Bounded literal body assertion for GET. |
| `timeout` | `duration` | 1, 2, 5 or 10 seconds; defaults to 10 seconds. |

## Response

| Field | Type | What it is |
| --- | --- | --- |
| `outcome` | `string` | up, unexpected_status, body_mismatch, dns_failure, tls_failure, network_failure, timeout or unknown. |
| `reason` | `string` | Precise unknown or refusal reason, separate from outage. |
| `status` | `uint32` | Actual HTTP status, zero if no response was received. |
| `sample_time` | `timestamp` | Server observation time. |

## Errors

- [`UNAUTHENTICATED`](/docs/api/errors/UNAUTHENTICATED) — No valid key or token was presented.
- [`PERMISSION_DENIED`](/docs/api/errors/PERMISSION_DENIED) — The key lacks the method's permission.
- [`RESOURCE_NOT_FOUND`](/docs/api/errors/RESOURCE_NOT_FOUND) — The named Resource does not exist or is not visible.
- [`INVALID_FIELD`](/docs/api/errors/INVALID_FIELD) — A field failed validation.

Every error arrives in the body [Errors](/docs/platform/errors) describes.

## Examples

**cURL**

```curl
curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/service_observations/service-observation:probe" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

**TypeScript**

```ts
const response = await sylphx.hosting.serviceObservations.probe({ name: 'orgs/acme/projects/shop/envs/production/service_observations/service-observation' })
```

**Rust**

```rust
let mut req = sylphx::hosting::ProbeServiceObservationRequest::default();
req.name = "orgs/acme/projects/shop/envs/production/service_observations/service-observation".to_string();
let response = sx.hosting().service_observations().probe(req).await?;
```

**CLI**

```bash
sylphx hosting service-observations probe orgs/acme/projects/shop/envs/production/service_observations/service-observation
```

**MCP**

```json
{ "method_id": "hosting.service_observations.probe", "args": {"name":"orgs/acme/projects/shop/envs/production/service_observations/service-observation"} }
```