---
# @generated by sylphx-gen. Do not edit.
title: "Observe an owner pool"
description: "`agents.owner_pools.observe` (POST /v1/{name}:observe): Records a live-metric observation for a member and applies the pool's demotion rules (`agents:qualify`, refused to the version's authors as in `:qualify`)."
type: reference
product: agents
summary: "Records a live-metric observation for a member and applies the pool's demotion rules (`agents:qualify`, refused to the version's authors as…"
updated: 2026-09-28
nav: false
---

Records a live-metric observation for a member and applies the pool's demotion rules (`agents:qualify`, refused to the version's authors as in `:qualify`). The platform computes each rule's baseline: the median of the member's first `baseline_observations` counted observations of the metric, set only when it is finite and positive. Values of a rule metric are lower-is-better and must not be negative. Once the baseline is set, a metric past `baseline * (1 + max_regression)` demotes a qualified member. Only `:qualify` brings a demoted member back.

- **Path** `POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/owner_pools/owner-pool:observe`
- **Scope** `agents:qualify`
- **Effect** `write` — a successful call changes state.
- **Collection** [owner_pools](/docs/api/owner_pools)

## Request

| Field | Type | What it is |
| --- | --- | --- |
| `name` | `string` | The owner pool. Required. |
| `agent_version` | `string` | The member version. Required. |
| `metrics` | `map<string, double>` | The observed value per metric over the caller's window, lower is better; 1 to 64. A demotion rule's metric is never negative. Required. |
| `samples` | `int64` | The number of outcomes the values summarize. Required. |

## Response

| Field | Type | What it is |
| --- | --- | --- |
| `agent_version` | `string` | The member version. Output only. |
| `model` | `string` | The model the version pins. Output only. |
| `state` | `OwnerPoolMemberState` | Qualified, refused or demoted. Output only. One of `qualified`, `refused`, `demoted`. |
| `suite` | `string` | The suite of the latest `:qualify`. Output only. |
| `scores` | `map<string, double>` | The scores of the latest `:qualify`. Output only. |
| `baseline` | `map<string, double>` | The baseline per demotion metric, computed by the platform from counted observations; a re-qualify keeps it. Output only. |
| `observed` | `map<string, double>` | The latest observation per metric. Output only. |
| `qualify_time` | `timestamp` | When it last qualified. Output only. |
| `demote_time` | `timestamp` | When it was last demoted. Output only. |
| `reason` | `string` | Why it was refused or demoted. Output only. |
| `update_time` | `timestamp` | When the state last changed. Output only. |
| `suite_version` | `string` | The suite version of the latest `:qualify`. Output only. |
| `result` | `string` | The suite result of the latest `:qualify`. Output only. |
| `qualifier` | `string` | The principal that recorded the latest `:qualify`. Output only. |

## 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.
- [`IDEMPOTENCY_KEY_REUSED`](/docs/api/errors/IDEMPOTENCY_KEY_REUSED) — An Idempotency-Key was reused with another body.
- [`IDEMPOTENCY_IN_PROGRESS`](/docs/api/errors/IDEMPOTENCY_IN_PROGRESS) — The first call with this Idempotency-Key is still running.

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/owner_pools/owner-pool:observe" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_version":"…","metrics":{},"samples":1}'
```

**TypeScript**

```ts
const response = await sylphx.agents.ownerPools.observe({ agentVersion: '…', metrics: {}, name: 'orgs/acme/projects/shop/envs/production/owner_pools/owner-pool', samples: 1 })
```

**Rust**

```rust
let mut req = sylphx::agents::ObserveOwnerPoolMemberRequest::default();
req.agent_version = "…".to_string();
req.metrics = Some(Default::default());
req.name = "orgs/acme/projects/shop/envs/production/owner_pools/owner-pool".to_string();
req.samples = 1;
let response = sx.agents().owner_pools().observe(req).await?;
```

**CLI**

```bash
sylphx agents owner-pools observe orgs/acme/projects/shop/envs/production/owner_pools/owner-pool
```

**MCP**

```json
{ "method_id": "agents.owner_pools.observe", "args": {"agent_version":"…","metrics":{},"name":"orgs/acme/projects/shop/envs/production/owner_pools/owner-pool","samples":1} }
```