---
title: "One official signal record for any signal_id and entity"
method: GET
path: "/gauge"
tags: ["gauge", "no-data-no-charge", "official-source", "descriptive-only"]
---

# One official signal record for any signal_id and entity

`GET /gauge`

## Request

- Base URL: `https://api.truthbear.co`
- URL: `https://api.truthbear.co/gauge`
- Auth: none declared

[SIGNAL+PROOF] One official signal record for any signal_id and entity: current reading against the OFFICIAL threshold ladder (band, distance-to-action) plus a 5-year same-season percentile so you can tell routine from unusual. 180+ signals across macro, weather, hazard, shipping, filings, crypto and lifecycle lines. Free coverage check first at /gauge/coverage. Descriptive only, never a forecast or advice. No data -> 422 no_charge, not billed. Also searched as: single record lookup; one measurement lookup; point in time datum.

## Query parameters

- `signal_id` string, required
- `entity` string, required

## Response `200`

Paid response

- object
  - `nature` string, required: Neutrality statement: GAUGE supplies observations and trend description only - no judgement, no prediction, no recommendation
  - `tier` string: Marker for the main single-point or history-series response (full / history-series); mutually exclusive with dim/addon
  - `update_status` object: Did the OFFICIAL source keep its own declared publication cadence? Separate dimension from freshness: a record can be freshness=recent and update_status=overdue at the same time. state: on_schedule | overdue | not_published | unknown
    - `state` string: on_schedule | overdue | not_published | unknown
    - `official_cadence` string, nullable: The cadence the official source declares for this line (hourly/daily/weekly/monthly/quarterly/yearly/as-events)
    - `overdue_days` integer, nullable: How many days past that cadence; null when it cannot be determined
    - `text` string: One-line human-readable form of the same fact
  - `signal_id` string: Signal id in genus.species ASCII binomial form (e.g. crypto.spot / macro.unemployment / shipping.route-disruption); full list at free /gauge/catalog
  - `entity` string: Monitored object id (e.g. btc / us / hormuz); full list at free /gauge/catalog or /gauge/preview
  - `entity_name` string, nullable: Human-readable name of the object
  - `snapshot_date` string: ISO-8601 date-time in UTC (e.g. 2026-07-24T00:00:00.000Z; aligned to midnight of that day)
  - `observed_at` string: Actual observation time of the data, ISO-8601
  - `data_age_hours` number, nullable: Age frozen at collection time (0 = same hour), for reference only - if a collector stalls this field stops moving. For freshness always use provenance.age_hours_now (computed at request time) and provenance.freshness; the threshold basis is in provenance.freshness_basis
  - `current` object, nullable: Current reading. The inner metric structure varies by signal (crypto -> {price_usd, volume_24h, ...}; shipping -> {wind_kmh, wave_height_m, ...}). Units are carried in the field-name suffix; see also standard_ruler.unit
  - `previous` object, nullable: Previous-period reading (a subset of the metrics in current; or {note} explaining that there is no previous value)
  - `change` object, nullable: Change, nested per metric: change.<metric> = {delta, direction, direction_reason?}, plus the scalar change.period (e.g. "vs_previous"). direction is one of rising/falling/stable/unknown - unknown means the direction CANNOT BE DETERMINED, it does not mean stable; in that case direction_reason carries a machine-readable cause: no-previous-record / metric-absent-in-previous / metric-absent-in-current / non-numeric-value
  - `trend_7d` object[], nullable: Array of the last 7 trend points; [] means this signal has no series yet or the series does not apply - it is not an error
  - `sources` object[], nullable: Source list [{name, value, weight, as_of, role, independent, relay_of?}]. independent:true = confirmed independent source; false = confirmed relay channel of another source (relay_of names the origin); null = independence unconfirmed (neither denied nor claimed). name/weight/independent/relay_of are record_hash core fields, so tampering with an independence claim breaks self-verification; as_of/value/role drift easily and are not hashed
  - `source_agreement_cv` number, nullable: Multi-source agreement, coefficient of variation (smaller = closer agreement). Present ONLY when two or more CONFIRMED-INDEPENDENT sources measure the same fact at the same time - see sources[].independent. Same source relayed through two channels does not count as independent, and two different time bases (daily mean vs spot) do not count as agreement. Single-source / unconfirmed independence / not applicable -> null
  - `standard_ruler` object, nullable: Official standard ruler (band / thresholds / normalized_index / pct_to_action, with unit and provenance); null when the line has no official ruler. Inner structure varies by signal
  - `stat_ruler` object, nullable: Statistical ruler: empirical percentile position across the last 5 same-season years; null when there are no statistics
  - `strata` object, nullable: Statistical strata: share of each official band over the last 5 same-season years plus the band the current value falls in; null when there are no statistics
  - `decision_points` object, nullable: {count, points:[{tag,current,swappable,how}], note} - decision points you can re-run with a swapped tag (one swapped tag = one call); leave it alone and the original context is the default, at no extra charge
  - `summary_en` string: Conditional - English one-line verdict derived at request time from this same record: reading + where it sits on the official ruler (distance to the first official alert) + seasonal percentile + direction, and staleness only when the data is actually old. Purely descriptive, never advice or forecast. Absent when this line carries no official ruler and no seasonal statistics (there is then nothing to conclude beyond the raw upstream reading). Not part of the record_hash core
  - `summary_zh` string, nullable: Human-readable one-line summary, IN CHINESE (zh-TW): reading + where it sits on the official ruler + statistical position. This is the HUMAN front-desk copy - machine consumers should read summary_en (English verdict) instead
  - `grade` string, nullable: Honest data-grade disclosure (e.g. "screening-level, not decision-grade")
  - `scope` string, nullable: Honest statement of scope and limits: monitoring is not forecasting, intelligence is not instruction, and the boundary of what is verifiable
  - `record_hash_verifiable` object, nullable: {mode:offline|via-endpoint, note}
  - `lifecycle` object, nullable: Lifecycle block (state / birth_at / end_at / death_type / context). Part of the record_hash v3 core, so offline recomputation must include it; null for non-lifecycle lines
  - `hash_core_version` integer, nullable: Core-contract version of record_hash (currently 3); use it to pick the right core composition when recomputing offline
  - `ots_status` string, nullable: RETIRED FIELD - always "pending" or null; this field is no longer updated and is kept only for older parsers. Anchoring is done per write-batch (previously one root per day): each batch of writes gets a Merkle root stamped via OpenTimestamps, typically confirmed into a Bitcoin block within hours. See GET /gauge/anchor?hash= for the inclusion proof and the block number.
  - `provenance` object, nullable: Data lineage: {served_from, data_as_of, oldest_leg_as_of, data_age_hours (frozen age, reference only), age_hours_now (age computed at request time - the real basis for freshness), freshness(fresh|recent|stale), freshness_basis (the cadence and threshold used for this row, as a string), dead_source (optional: upstream frozen or discontinued), data_lineage:[{signal,traceable_to,uncertainty,record_hash,...}], validation_status}. Freshness is cadence-aware, so monthly/quarterly/annual official lines are not misjudged against a 24h rule; the same basis is used by free /gauge/coverage. Buyers can trace back to the official source
  - `source_ref` string, nullable: Official source URL (provenance)
  - `source_tier` string, nullable: Source tier: T1 (first-hand official) / T2 or T2-<subtype, e.g. T2-exchange> (observable, curated) / screen-viewpoint; null = untiered (see unverified)
  - `record_hash` string, nullable: sha256:<64hex> (contract A v3, binds the values plus provenance)
  - `_citation` object, nullable: Offline-verifiable citation: {statement_type, not_advice:bool, claim, fact, source, record_hash, signature(Ed25519), key_id, issuer_DID(did:key), verify_url} - the trust root for zero-trust self-verification
  - `unverified` boolean: true = the source is untiered (source_tier is null); buyers and agents can filter on this

## Other responses

- `402`: Payment Required
- `422`: No data for this query - no_charge:true, you are NOT billed

---

[API](https://skmtc.dev/truthbear/apis/truth-bear-verifiable-screening-intelligence-for-ai-agents-g.md) · [All operations](https://skmtc.dev/truthbear/apis/truth-bear-verifiable-screening-intelligence-for-ai-agents-g/llms.txt) · [OpenAPI document](https://skmtc.dev/truthbear/apis/truth-bear-verifiable-screening-intelligence-for-ai-agents-g/revisions/35744dfa4550?raw)