# Reading results

## One object

`GET /v1/objects/{object_id}` returns the latest answer for every signal that
has one, and the enabled signals that don't yet:

```json
{
  "object_id": "user-42",
  "event_count": 7,
  "analysis": [
    { "key": "is_scammer", "type": "noul", "noul": 0.91, "model": "model-1", "computed_at": "2026-09-27T10:00:05Z" },
    { "key": "buyer_intent", "type": "choice", "choice": "ready_to_buy",
      "probabilities": { "browsing": 0.05, "comparing": 0.15, "ready_to_buy": 0.8 },
      "confidence": 0.8, "model": "model-1", "computed_at": "2026-09-27T10:00:05Z" }
  ],
  "pending": ["trust_score"]
}
```

Only the fields for a signal's type are set: `noul` for noul signals, `score`
for score signals, `choice` for choice signals, plus `probabilities` and
`confidence` for the latter two.

An object with no events and no answers is a `404`.

### Caching

Reads are cached for a few seconds. The `X-Cache` header says whether a
response was a `HIT` or a `MISS`. Ingesting events and completed analyses
invalidate the object's cache entry, so new answers show up as soon as they
are stored.

## Waiting for an analysis

After ingesting, answers arrive once the debounced analysis has run. To wait
for them:

1. **Webhooks (recommended).** Register an endpoint and get
   `analysis.completed` with the answers. See [Webhooks](https://sigwise.ai/docs/guides/webhooks.md).
2. **Polling.** Read the object after `analysis_delay_ms` plus a margin, and
   check `computed_at`. Poll gently; there is no benefit to polling faster than
   once a second.
3. **Inline.** For a decision you need now, ingest with `"wait": true`. See
   [Direct moderation](https://sigwise.ai/docs/guides/moderation.md).

## Many objects

`GET /v1/objects` returns a page of objects with their answers:

| Parameter | |
|-----------|---|
| `q` | A substring of the object ID or display name, or a signal query such as `is_scammer >= 90` (see [Search and conditions](https://sigwise.ai/docs/guides/queries.md)). |
| `sort` | `recent` (default), `flagged` (highest yes/no probability first) or `trust` (highest score first). |
| `limit` | 1–200, default 100. |
| `offset` | For the next page. |

```bash
curl "$API/v1/objects?q=is_scammer%20%3E%3D%2090&sort=flagged&limit=50&api_key=$ANALYZE_API_KEY" \
  -H "Authorization: Bearer $(sign)"
```

`GET /v1/overview` returns account-wide totals: how many objects exist and are
analyzed, events in the last 24 hours, flagged objects, and each signal's
distribution of answers.