Query historical state
Separate when a source fact was valid from when Gridstate learned it.
Use Gridstate’s bitemporal parameters to query real-world history or replay the information available to Gridstate on a past date.
Choose the time dimension
The two parameters answer different questions:
| Parameter | Question it answers |
|---|---|
valid_at | What did the source say was true on this date? |
known_at | What had Gridstate ingested by this date? |
Use valid_at to inspect the source fact’s real-world validity interval:
curl -G "$GRIDSTATE_API_BASE/v1/queue-records" \
-d state=TX \
-d valid_at=2026-03-01 \
-H "Authorization: Bearer $GRIDSTATE_API_KEY" \
-H "Gridstate-Version: 2026-08-24"A project can be valid as active in March even if Gridstate did not learn about that revision until April. The two parameters preserve that distinction.
Make a historical query reproducible
Pin the dated Gridstate-Version header with the time parameter. The version fixes the response contract, while the time parameter fixes the requested evidence state.
Use the parameter that matches your audit question
Choose valid_at when reviewing source history. Choose known_at when reproducing a prior Gridstate decision or assessment.
Monitor recorded changes
Gridstate stores status updates as versioned events instead of overwriting them. Query /v1/change-events to retrieve bounded before-and-after changes.
Zero returned events means no matching change exists in the acquired Gridstate evidence. It does not prove that nothing changed outside the acquired sources.