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

# Response format

> Where Hive attaches provenance across the three surfaces that return it.

Responses are typed and bounded, and material ones carry provenance. Where that provenance
sits depends on which surface answered.

## MCP tools

Tools reached through discovery attach a top-level `_hive` object alongside the payload:

```json theme={null}
{
  "_hive": {
    "receipt_id": "9f2c…",
    "provider": "CoinGecko",
    "tool": "get_price",
    "runtime_status": "ok",
    "fetched_at": "2026-08-19T14:22:07Z",
    "cache_status": "miss",
    "duration_ms": 184
  }
}
```

`_hive` also carries `receipt_version`, `server_version`, `input_digest`, and
`result_digest`. The digests are SHA-256 self-checks over the canonical arguments and the
normalized payload. They let you detect accidental mutation; they are not server signatures.

## Hero tools

The three hero tools add a `source_receipt` describing the provider call they made underneath,
alongside their own top-level `_hive`:

```json theme={null}
{
  "source_receipt": {
    "provider": "CoinGecko",
    "tool": "get_price",
    "runtime_status": "ok",
    "fetched_at": "2026-08-19T14:22:07Z",
    "cache_status": "hit",
    "source": "cached",
    "receipt_id": "9f2c…"
  }
}
```

A hero response carries both objects, so do not treat a missing `_hive` as the way to detect
one. `source` is an enum with four values: `live`, `cached`, `fallback`, and `unavailable`.

Same three fields you care about, different container. See [receipts](/concepts/receipts).

## CLI

`hive ... --json` is a third shape. It wraps everything in an envelope, and the provenance
lands in `meta` rather than `_hive` or `source_receipt`:

```json theme={null}
{
  "ok": true,
  "data": {},
  "meta": {
    "tool": "get_token_price",
    "provider": "Hive",
    "runtime_status": "ok",
    "source": "live",
    "truncated": false,
    "quota_remaining": 9775
  }
}
```

`meta.tool` is the tool you called and `meta.provider` is the surface that served it, so a hero
tool reads `Hive` here. The upstream provider for that call is in `source_receipt` inside
`data`, not in `meta`.

`--jq` filters `data` only, so `--jq '.price'` reaches into the payload and not the envelope.
`--jq '.ok'` returns nothing, because `ok` lives on the envelope.

## runtime\_status values

`runtime_status` is an enum, not free text:

| Value           | Meaning                                                                                                                                       |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `ok`            | The call succeeded against a healthy provider                                                                                                 |
| `invalid_input` | Your arguments failed validation, or the venue and method combination is unsupported. Fixable by correcting the call                          |
| `missing_key`   | The provider is not configured                                                                                                                |
| `plan_required` | The upstream provider's own plan, quota, or credits block the call, not your Hive plan                                                        |
| `rate_limited`  | Throttled                                                                                                                                     |
| `degraded`      | The tool exists, but the provider is temporarily unavailable or unstable. Retry after a pause, and treat any partial result as low confidence |
| `failing`       | The call returned an unexpected error, upstream or inside Hive. Read `cause` and `next_action` before deciding what to do                     |

`invalid_input` is worth handling separately: it is not an outage, so retrying unchanged will
fail the same way.

## Cache fields

`cache_status` tells you whether the response came from Hive's cache. On a hit, `observed_at`
is when Hive first saw the data and `cache_age_ms` is how long ago that was.

A `cache_age_ms` of zero means Hive fetched from the provider just now. It does not promise
that the provider's own underlying datum is current.

## Normalization fields

Where Hive knows something is off about a datapoint, it says so in a field rather than
dropping the row:

| Field               | Meaning                                                |
| ------------------- | ------------------------------------------------------ |
| `is_delisted`       | No longer actively traded on the venue                 |
| `is_price_suspect`  | Diverges enough from other sources to warrant a check  |
| `funding_mechanism` | How this venue calculates funding, since venues differ |

Your agent decides what to do with a flagged row. Hive does not filter it out for you.

## Bounded output

Where a list-returning tool supports `limit`, `page`, `per_page`, or `offset`, use them. Not
every tool takes all four, so check the schema with `get_api_endpoint_schema` or
`hive tools info <name>`.

Hive caps total response size regardless of what you ask for: 25,000 tokens, or roughly 100,000
characters. Responses trimmed to fit set `truncated` to `true`. An unbounded response would burn
the context your agent needs for the actual task.

## Errors

Failures return an error object naming the cause and the next action. See
[errors](/reference/errors).