Dataset sub-resources

Beyond search and dossiers, /v1/ exposes each entity's underlying datasets as row-level sub-resources — the same elected figures the Pulse product renders, served as structured rows you can ingest. This guide covers the conventions they share and what each dataset carries; the exact row schemas live on each endpoint's reference page.

Shared conventions

Elected figures only. Pulse extracts the same figure from many filings; an election process picks the authoritative row. These endpoints serve the elected layer — one row per period/estimate, not every raw extraction. Each row carries its provenance: source_publication_id, source_url (anchored to the page where known), published_date, and source_count (how many source rows back the elected figure).

Everything returned at once, except drill results. Per-entity production, reserves, economics, and ownership row counts are bounded, so those endpoints return every row as {"results": [...], "count": N} with no paging. Drill results can run long and are paginated — see Pagination and enumeration.

Kilograms plus labels. Physical quantities are normalized to the commodity's canonical mass basis under *_kg keys. Most commodities use elemental metal; the Rare Earth Elements group uses source-stated TREO. Niobium stores elemental Nb canonically and displays it as Nb₂O₅ only when the source species makes that conversion valid. Figures remain comparable within a commodity across reporting units. Each is paired with a *_label — the same figure formatted in the commodity's customary unit (e.g. 1,000 koz, 12.4 Mt). Compute with the _kg value; display the label. The commodity registry carries each commodity's display species and source-to-canonical conversion factor if you need to re-derive customary units yourself.

Ownership basis is explicit. Every production and reserves row states its basis: company rows are attributable (the company's share of each operation), asset rows are 100_percent (the whole operation regardless of who owns it). A company row and an asset row for the same operation are not comparable without accounting for that.

Errors. An unknown entity id is a 400 invalid_argument; a valid entity with no data returns 200 with empty results — absence of data is not an error.

Production

One row per elected production period per commodity, newest first. Rows distinguish value_type (Actual vs Projected guidance, with projection_origin naming the guidance source) and output_measure (produced, sold, or refined). Unit costs come as three typed projections, each in USD per kilogram of the commodity's canonical mass basis with a formatted label: aisc_per_kg_in_usd, c1_per_kg_in_usd, and total_cash_cost_per_kg_in_usd. A trimmed asset row:

{
  "commodity": { "symbol": "Au", "name": "Gold" },
  "basis": "100_percent",
  "year": 2025,
  "quarter": 2,
  "period_label": "2025 Q2",
  "value_type": "Actual",
  "canonical_output_kg": 3110.35,
  "output_label": "100 koz",
  "output_measure": "produced",
  "aisc_per_kg_in_usd": 45139.0,
  "aisc_label": "$1,404/oz",
  "source_publication_id": 98765,
  "published_date": "2025-07-24"
}

Reserves & resources

One row per elected estimate per commodity per effective date, newest first. Each row breaks the estimate into tiers — reserves_kg (proven + probable), resources_kg, measured_indicated_kg, inferred_kg — each with a formatted label and an ore-grade label, plus total_inventory_kg, the total endowment computed per the row's resources_inclusivity (reserves + resources when resources are exclusive of reserves; resources alone when inclusive). is_equivalent flags metal-equivalent figures (commodity_label shows e.g. AuEq), and reporting_standard names the code the estimate was prepared under (jorc_2012, sk1300, …) — null or other when the source doesn't state a recognized code.

Economic assessments

Every published study scenario for an asset, newest effective date first — a study's base case and its alternate scenarios each get a row (scenario_label, is_base_case).

source_kind tells you whose model produced the row's figures: study (the code-compliant technical report itself — NI 43-101 / JORC / SK-1300, including CPRs and ITAs), study_restatement (the owner's own figures carried by a press release, presentation, or periodic report — including a third party repeating figures it attributes to the owner), or third_party_model (broker research, consensus tables, independent-expert DCFs — figures built on the third party's own assumptions). Third-party scenarios stay in this endpoint so you can compare analyst views against the company's studies, but they never populate the asset's headline economics. source_kind is null on rows extracted before the field was introduced; classification backfills progressively via re-extraction.

Monetary figures come twice:

• In whole units of the stated currency (never millions) as reported by the study.
• As canonical_*_in_usd — normalized to USD on a 100% project basis for cross-asset comparison. When a figure can't be normalized (for example, the ownership factor is unresolvable), the canonical field is null — it is never estimated.

Each scenario nests three arrays: price_assumptions (the study's price deck), cost_metrics, and npv_curve (NPV at alternate discount rates), alongside project parameters — mine life, payback, throughput, recovery, grades, and projected output.

Drill results

One row per drill disclosure — a publication reporting drill results on the asset or an asset in its subtree — newest first, paginated with limit/offset. Each disclosure carries its source publication, the headline intercept, and a holes array; each hole carries its collar (WGS84 position, dip, azimuth, end-of-hole depth) and its intercepts (depths, interval, commodity, grade and unit, true width, cut-off). Only top-level intercepts are included — sub-intervals of a reported intercept are excluded so intervals are never double-counted.

Ownership

/v1/companies/{id}/mining-assets/ and /v1/mining-assets/{id}/companies/ are the two directions of the same company–asset ownership edge, current relations first with historical relations included — the full timeline, so you can reconstruct how ownership changed hands, not just who holds it today. Field names match the corresponding dossier sections, including ownership_fraction — the equity or joint-venture share as a fraction in [0, 1], null for passive interests like royalties and streams, which have a role but no equity share — and source_url for the relation's source document.

The commodity registry

GET /v1/commodities/ returns the full curated registry every other endpoint's commodity references point into: units, display species with conversion factors, capability flags, and a spot-price snapshot. It's bounded reference data, returned in full with no pagination — fetch it once per session and use it to interpret commodity references, *_kg conversions, and price units everywhere else. The extraction capabilities are independent: enabled_for_production_extraction, enabled_for_reserves_extraction, enabled_for_drill_extraction, and enabled_for_economics_extraction state which structured dataset can represent that commodity.

Go deeper

• Pagination and enumeration — the paging convention drill results share with the search endpoints.
• Incremental sync — knowing when to re-fetch these datasets.