API workflow guardrail
Use freshness metadata before you trust a latest price
Latest-price responses can now include freshness fields that help your application distinguish current, delayed, and stale source observations. That makes spreadsheet refreshes, dashboards, and internal checks easier to handle conservatively.
What to check
Start with the status fields before using a latest value in a customer-facing or operational workflow.
Freshness metadata is additive; existing price fields remain available.
Use the metadata for workflow decisions instead of assuming every latest response is equally current.
Tie alerts to your own reporting tolerance, approval process, and benchmark set.
current
The latest observed price is within the expected age window for that benchmark.
delayed
The latest observed price is older than expected, but not yet past the stale threshold.
stale
The latest observed price is old enough that your workflow should treat it as a warning state.
Response shape
Read the freshness block alongside the price
The metadata is designed for defensive workflows. A current response can be used normally. A delayed or stale response should trigger the handling path your team has chosen.
Latest price request
Use Token authentication for customer API requests.
curl -H "Authorization: Token YOUR_API_KEY" \ "https://api.oilpriceapi.com/v1/prices/latest?by_code=WTI_USD"
{
"status": "success",
"data": {
"code": "WTI_USD",
"price": number,
"created_at": "ISO-8601 timestamp",
"data_status": "current",
"freshness": {
"status": "current",
"age_seconds": number,
"expected_max_age_seconds": number
}
}
}Stale handling
Make stale data visible before it becomes a silent assumption
When a latest row is stale, responses can include stale flags and a stale reason. Treat those as workflow signals: show a warning, pause automation, or route the case for review.
Read data_status first.
Display the latest price with a visible warning when stale is true.
Log stale_reason for internal diagnosis without exposing API keys or payloads.
Fall back to historical or raw checks when your workflow requires source-date confirmation.
Stale response fields
These fields are present when the latest observation should not be treated as current.
{
"data_status": "stale",
"freshness": {
"status": "stale",
"age_seconds": number,
"expected_max_age_seconds": number
},
"stale": true,
"is_stale": true,
"stale_reason": "no_recent_data"
}Practical pattern
Pair latest checks with the workflow they protect
Spreadsheets and dashboards
Show the price, timestamp, and status together so users know when a refresh needs review.
Automated workflows
Keep stale handling explicit: warn, pause, or route to a manual check instead of continuing silently.