gauge
no-data-no-charge
official-source
descriptive-only

One official signal record for any signal_id and entity

[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.

get/gauge

Request

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

Query parameters

signal_idstring required
Example:hydrology.river-level

required - signal id in genus.species ASCII form (e.g. hydrology.river-level, crypto.spot, macro.unemployment, earthquake.current_activity). Full list: free GET /gauge/catalog

entitystring required
Example:07010000

required - monitored object id, PAIRED WITH signal_id (e.g. 07010000 for hydrology.river-level, japan for earthquake.current_activity). Valid pairs: free GET /gauge/catalog?signal_id=<signal_id> -> signals[0].entities[]

Response

Paid response

naturestring required

Neutrality statement: GAUGE supplies observations and trend description only - no judgement, no prediction, no recommendation

tierstring

Marker for the main single-point or history-series response (full / history-series); mutually exclusive with dim/addon

signal_idstring

Signal id in genus.species ASCII binomial form (e.g. crypto.spot / macro.unemployment / shipping.route-disruption); full list at free /gauge/catalog

entitystring

Monitored object id (e.g. btc / us / hormuz); full list at free /gauge/catalog or /gauge/preview

entity_namestring nullable

Human-readable name of the object

snapshot_datestring

ISO-8601 date-time in UTC (e.g. 2026-07-24T00:00:00.000Z; aligned to midnight of that day)

observed_atstring

Actual observation time of the data, ISO-8601

data_age_hoursnumber 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

currentobject 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

previousobject nullable

Previous-period reading (a subset of the metrics in current; or {note} explaining that there is no previous value)

changeobject 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_7dobject[] 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

sourcesobject[] 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_cvnumber 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_rulerobject 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_rulerobject nullable

Statistical ruler: empirical percentile position across the last 5 same-season years; null when there are no statistics

strataobject 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_pointsobject 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_enstring

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_zhstring 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

gradestring nullable

Honest data-grade disclosure (e.g. "screening-level, not decision-grade")

scopestring nullable

Honest statement of scope and limits: monitoring is not forecasting, intelligence is not instruction, and the boundary of what is verifiable

record_hash_verifiableobject nullable

{mode:offline|via-endpoint, note}

lifecycleobject 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_versioninteger nullable

Core-contract version of record_hash (currently 3); use it to pick the right core composition when recomputing offline

ots_statusstring 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.

provenanceobject 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_refstring nullable

Official source URL (provenance)

source_tierstring nullable

Source tier: T1 (first-hand official) / T2 or T2-<subtype, e.g. T2-exchange> (observable, curated) / screen-viewpoint; null = untiered (see unverified)

record_hashstring nullable

sha256:<64hex> (contract A v3, binds the values plus provenance)

_citationobject 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

unverifiedboolean

true = the source is untiered (source_tier is null); buyers and agents can filter on this

Changes

No recorded changes to this operation across all 1 revision of this API.