Spreads & Margins

Premium analytics endpoints for crack spreads, basis, refinery margin, curve structure, and physical premiums.

Access

Available on Developer and above, and during an active 7-day trial. Free-plan keys receive 403 with the message Calculated metrics require a paid plan (Developer and above).

Endpoints

Family	Endpoints
Crack spreads	`/v1/spreads/crack`, `/historical`, `/all`
European gasoil crack	`/v1/spreads/gasoil-crack`
Basis	`/v1/spreads/basis`, `/historical`, `/all`
Margins	`/v1/spreads/margin`, `/historical`, `/all`
Curve structure	`/v1/spreads/curve-structure`, `/all`
Physical premium	`/v1/spreads/physical-premium`, `/historical`, `/all`

Common Parameters

Parameter	Type	Description
`code`	string	Spread or market code where supported
`date`	date	Snapshot date
`start_date`, `end_date`	date	Historical range (ISO 8601). `from`/`to` are not read; the default window is the last 30 days
`limit`	integer	Maximum records

Common Response Shape

{
  "status": "success",
  "data": [
    {
      "code": "WTI_321_CRACK",
      "value": 24.15,
      "currency": "USD",
      "unit": "barrel",
      "period": "2026-07-15",
      "updated_at": "2026-07-15T14:30:00.000Z"
    }
  ]
}

Historical Coverage Fields

/v1/spreads/crack/historical returns two fields beside the series so you can see what was actually returned:

Field	Description
`coverage`	`from`, `to`, `observations`, and `complete` for the rows returned. `period` echoes what was requested; `coverage` describes what came back. Compare the two before assuming a widened window returned more data.
`data_revised_at`	When the underlying price rows for the window were last modified. If it is later than the copy you hold, the history was restated — refetch.

Error Cases

Status	When
`400`	Missing or invalid query parameter
`401`	Missing or invalid API key
`403`	Plan without calculated metrics (Free), or an expired trial
`402`	Plan/quota issue

Data Rights

Spreads are derived analytics. Public display, redistribution, or downstream resale requires review under the Data Usage Policy.