> ## 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,
    "credit_cost": 1,
    "credits_used": 1,
    "credits_remaining": 9774
  }
}
```

`_hive` also carries `receipt_version` (always `"1.0"`; the credit fields were added without
bumping it), `server_version`, `input_digest`, and `result_digest`. `credit_cost`,
`credits_used` and `credits_remaining` are described under
[receipts](/concepts/receipts#what-the-call-cost); on an error the object also carries
`cause`, `next_action` and `doc_url`. 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,
    "credit_cost": 1,
    "credits_used": 1,
    "credits_remaining": 9775,
    "quota_remaining": 9775
  }
}
```

`quota_remaining` is a deprecated alias of `credits_remaining` kept for one release; read
the new name. `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 the same four legs on every surface: `code`, `message`, `cause`,
`next_action`, plus `retryable`, `retry_after` when a wait is known, and `doc_url`, an anchor
on the [errors page](/reference/errors). REST keeps `type`, `param` and `request_id`
alongside; JSON-RPC cap errors carry the fields under `error.data`; the CLI keeps
`suggestion` as an alias of `next_action` for one release.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.