Data Freshness and Source Timestamps

OilPriceAPI returns latest available values with source timestamps. Refresh cadence varies by source, market hours, dataset, and plan. There is no single sitewide update interval.

Review the versioned Product Facts before publishing a freshness claim.

Interpret the Timestamp

Read the timestamp returned for the individual value. Do not assume that the HTTP response time is the time the underlying source value changed.

An abridged response can look like this:

{
  "data": {
    "code": "BRENT_CRUDE_USD",
    "price": 76.42,
    "currency": "USD",
    "created_at": "2026-07-18T14:35:00Z",
    "source": "example_source"
  }
}

The source and response shape can vary by endpoint. Treat the returned timestamp as data to evaluate, not as a universal freshness guarantee.

Define a Staleness Policy

Choose a maximum age based on the workflow, dataset, market calendar, and account. A reporting dashboard can often tolerate a different age than an operational alert.

from datetime import datetime, timedelta, timezone

def is_stale(created_at, max_age):
    observed_at = datetime.fromisoformat(created_at.replace("Z", "+00:00"))
    return datetime.now(timezone.utc) - observed_at > max_age

max_age = timedelta(minutes=30)  # Your workflow policy, not an API guarantee.
if is_stale(response["data"]["created_at"], max_age):
    show_stale_state()

Production integrations should:

  1. Store the value and its source timestamp together.
  2. Display or log an explicit stale state when the chosen threshold is exceeded.
  3. Handle missing values and null fields.
  4. Retry transient transport failures with bounded exponential backoff.
  5. Avoid silently substituting an old value as if it were current.

Why Cadence Varies

Cadence can differ because:

  • source publishers update on different schedules;
  • market hours, weekends, and holidays affect availability;
  • some datasets are intraday while others are daily, weekly, or monthly;
  • plan and account entitlements can affect dataset access and delivery method;
  • upstream delays and maintenance can postpone an expected update.

Check the endpoint documentation and the timestamp returned by the API. Contact support when a specific account or dataset needs a documented operational expectation.

Polling and Push Delivery

Polling more frequently does not make an upstream source update more frequently. Set a polling interval that respects the account limit and the application's staleness policy.

Webhook or WebSocket delivery, where enabled for the account and dataset, still depends on upstream data arrival. Do not describe push delivery as an exchange execution feed or assume it removes source latency.

Historical and Derived Data

Available history ranges and aggregations vary by commodity, dataset, plan, and account entitlement. Preserve source timestamps and methodology when computing derived values.

Before displaying or redistributing data outside an internal workflow, review the Data Usage Policy. API access is separate from ownership or redistribution rights in underlying source data.

Support

Last Updated: