> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noxint.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# read

> One call, the whole picture: the current situation for an asset across every domain

`read` is the situation report. One call assembles the current picture for an
asset across every domain that applies to its plane, so your agent does not
stitch together `price`, `funding`, `technicals`, and the rest by hand. This
is the call an agent makes first, and often the only one it needs. It works on
both planes: a crypto asset returns a market assessment and a headline; an
equity returns a headline.

```bash theme={null}
curl -H 'Authorization: Bearer nx_your_key' \
  'https://noxint.ai/api/v1/read?id=crypto:bitcoin'
```

## Parameters

<ParamField query="id" type="string">
  One canonical asset ID. Mutually exclusive with `ids`.
</ParamField>

<ParamField query="ids" type="string list">
  Two to ten distinct canonical asset IDs, comma-separated. Mutually exclusive
  with `id`.
</ParamField>

You pass either `id` or `ids`, never both. `read` is the only situation
operation and takes no other parameters. Nothing to tune, nothing to get
wrong.

## Billing

One credit per distinct returned asset. A single `id` costs one credit. A
batch reserves up to ten and settles the actual number delivered, so
`ids=crypto:bitcoin,crypto:ethereum` costs two credits when both are returned.
An asset that is refused rather than returned is not charged.

## Response

The envelope is a single `{"data": ...}` object. Each asset carries a
`headline`, an `assessment` (crypto only), and, when anything cannot be
served, an `unavailable` block. Freshness clocks (`as_of`, `status`,
`next_update_at`) travel with the data, and measured values arrive with
their own percentile against the stated `baseline`, so every number lands
already ranked against its own history. A trimmed crypto example:

```json theme={null}
{
  "data": {
    "asset_id": "crypto:bitcoin",
    "symbol": "BTC",
    "name": "Bitcoin",
    "class": "core",
    "as_of": "2026-07-13T08:00:00Z",
    "status": "live",
    "next_update_at": "2026-07-13T08:05:00Z",
    "baseline": { "window": "90d", "cadence": "1h", "n": 2160 },
    "assessment": {
      "positioning": { "state": "mild_long", "rule": "funding_oi@1" },
      "structure": { "trend_state": "down", "rule": "structure_invalidation@1" },
      "flow": { "state": "balanced", "rule": "taker_flow@1" },
      "cascade_risk": { "level": "low", "rule": "shelf_cascade@1" }
    },
    "headline": {
      "price_usd": 62719.1,
      "return_24h_pct": { "value": 0.98, "pctl": 75 },
      "funding_rate_8h_pct": { "value": 0.006, "pctl": 87 },
      "oi_change_24h_pct": { "value": -0.23, "pctl": 49 },
      "trend_state": "down"
    }
  }
}
```

The `assessment` states are rule-derived and each names the rule version
that produced it. A component that cannot be delivered is listed under
`unavailable` with a typed reason rather than filled with a placeholder. The
contextual shape `{"value": ..., "pctl": ...}` appears on measurements that
carry a percentile; where a value is a plain number it is returned directly.