---
title: "Query historical Trail Heat snapshots"
method: GET
path: "/v1/agent/historical-trailheat"
tags: ["Intelligence"]
---

# Query historical Trail Heat snapshots

`GET /v1/agent/historical-trailheat`

## Request

- Base URL: `https://www.farmdash.one/api`
- URL: `https://www.farmdash.one/api/v1/agent/historical-trailheat`
- Auth: HTTP bearer

Requires Pioneer or Syndicate access through the TollBooth. Scout receives
402 even within its free quota. Requires the trail_heat_snapshots store;
missing storage or query failures return 503 rather than fabricated history.
With protocolId, returns that protocol's daily history; without it, returns
the latest snapshot per protocol in the requested window. Legacy editorial
and canonical-live vintages are not quantitatively comparable; inspect
data_evidence, evidence_vintage and data_quality before trend analysis.

## Query parameters

- `protocolId` string
- `days` integer

## Headers

- `X-ClawHub-Skill` string

## Response `200`

Stored snapshots with explicit scoring provenance

- object
  - `protocolId` string: Present only for a specific protocol query; sanitized identifier
  - `count` integer, required
  - `days` integer, required
  - `score_semantics` string, required
  - `data_quality` object, required
    - `mode` 'canonical' | 'vintage_mix' | 'legacy_only', required
    - `vintage_mix_warning` string, nullable, required
  - `snapshots` object[], required
    - `protocolId` string, required
    - `protocolName` string, required
    - `score` number, nullable, required
    - `components` unknown, required
    - `metadata` unknown, required
    - `data_evidence` unknown, required
    - `evidence_vintage` 'canonical-live' | 'legacy-editorial-heuristic', required
    - `snapshotDate` string, date, required

## Other responses

- `402`: Pioneer access required or TollBooth payment wall; payment does not change execution authority
- `429`: Rate limit exceeded
- `503`: Historical storage is not ready (feature_not_ready) or historical_trailheat_unavailable

---

[API](https://skmtc.dev/farmdash/apis/farmdash-agent-api.md) · [All operations](https://skmtc.dev/farmdash/apis/farmdash-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/farmdash/apis/farmdash-agent-api/revisions/96310281f58c?raw)