BBP API Reference
A commercial REST API for physics-based ground-motion simulations from the
SCEC Broadband Platform
Submit a scenario, validation, or observed-comparison job, or an SW4 wavefield simulation; poll for completion; download artifacts.
The BBP build served — version, source commit and data release — is returned by
GET /v1/catalog/versions, which is authoritative;
this page deliberately does not name a version, because a number written into prose goes stale
silently and one already did.
Preview — service not yet publicly available
The hosted BBP API is being prepared for launch. This page documents the interface so you can plan an integration; access keys and the metered service are not yet open to the public. Watch the System Update Log for availability.
Getting Started
The API is reached under the /v1/
base path — this domain is the API, so there is no prefix to strip. Every request authenticates with your BBP Services API key, passed as a bearer token:
Your API key is the same one issued to your BBP Services account (see your
account page). Usage is metered per account — compute time and stored-artifact bytes are
tracked and exposed at GET /usage. Job results are retained for a
limited window and then swept, so download artifacts you need to keep.
https://bbpservices.net/v1 ·
responses are wrapped in a { "data": ... } envelope.
Velocity-Model Regions
A simulation runs against a regional 1-D crustal velocity
model. Each installed region (see GET /catalog/regions)
covers a native geographic extent; pass its id as region
in a job spec. The map shows the extents of the California regions this service hosts.
region
in a job spec and what GET /catalog/regions returns.
The two correspond as follows:
| Name on the map | Package id (use this in the API) | Area covered |
|---|---|---|
| NoCal | NoCal500 |
Northern California, including the Bay Area |
| CenCoast | CentralCal500 |
Central Coast Ranges, including Parkfield |
| Southern Sierra Nevada | SouthernSierra500-2 |
Southern Sierra Nevada and Owens Valley |
| Mojave | Mojave500 |
Mojave Desert, including Ridgecrest |
| SoCal | LABasin500 |
Southern California, including the Los Angeles basin |
The 500 in a package id is the model's minimum shear-wave
velocity in m/s, not a region name. SouthernSierra500-2 ends
in -2 because it is the second release of that package.
Always send the package id exactly as GET /catalog/regions
reports it; the map names are not accepted.
Catalog
Read-only lookups describing what the platform can run: simulation methods, installed velocity-model regions, packaged validation events, BBP versions, and the compute engines served.
GET
/catalog/methods
Lists the ground-motion simulation methods the platform supports
(e.g. Graves & Pitarka, GP). The id values are what you pass as method in a job spec.
{
"data": [
{ "id": "GP", "name": "Graves & Pitarka" }
]
}
GET
/catalog/regions
Lists the crustal velocity-model regions whose Green's-function
packages are installed on the host. The id values are valid for the region field of a scenario/comparison job.
{
"data": [
{ "id": "LABasin500", "name": "LA Basin (500 m/s)" }
]
}
GET
/catalog/validation-events
Lists the SCEC-packaged historical events available for a
validation job (e.g. Northridge, NR), each with bundled source and observed data.
{
"data": [
{ "id": "NR", "name": "Northridge 1994" }
]
}
GET
/catalog/versions
Lists the BBP builds the host can run, each with the source
repository, ref and commit it was compiled from and the SCEC data release its Green's functions come from.
Pass an id as
bbp_version in a job spec, or
omit the field to run the default. An unknown id is a 422.
Read from the running image's own build provenance rather than a
configured string. "provenance": "unverified" means the
deployment cannot confirm which source it compiled, so treat its version as a label rather than a checked fact.
{
"data": [
{
"id": "22.4.0",
"status": "available",
"default": true,
"provenance": "git",
"source_repo": "https://github.com/SCECcode/bbp.git",
"source_ref": "v22.4.0",
"source_commit": "26972594caba029463c85f384f15bc26bb4a0d66",
"data_release": "22.4.0"
}
]
}
GET
/catalog/engines
Lists the engines this deployment runs: bbp
(broadband seismograms, the modes above) and sw4 (low-frequency wavefield simulations).
Check "enabled": true on sw4 before submitting an SW4 job, rather than
inferring it from a version number. The limits block gives the most sites per job, the memory
ceiling, the SRF upload limit, the supported grid spacings and the highest frequency.
sw4_commit is the SW4 source commit the service runs, and
sw4_commit_source says where that value comes from: "image" (read in the SW4
image itself) or "setting" (configured beside the image). Null means the deployment cannot say.
{
"data": [
{ "id": "bbp", "enabled": true, "modes": ["scenario", "validation", "comparison"],
"versions": ["dev-2026.07", "22.4.0"] },
{
"id": "sw4", "enabled": true, "modes": ["sw4"],
"sw4_commit": "03cb7e8d77aa32ecd671a8fa0e146a9ccf2c1846",
"sw4_commit_source": "setting",
"limits": { "max_sites": 5000, "max_memory_gib": 240.0, "max_srf_mb": 200.0,
"grid_spacings_m": [100, 200, 400], "max_f_max_hz": 1.0 },
"sources": ["from_job", "srf_upload"],
"velocity_models": ["bbp_1d"],
"priorities": ["standard"]
}
]
}
Jobs
Submit a simulation, then poll its status or stream its events. A job runs one or more stochastic realizations and produces downloadable artifacts. Jobs are scoped to your account — you can only see and act on your own.
POST
/jobs
Submits a job spec keyed by mode:
scenario (a synthetic rupture at one or more stations) or
validation (a packaged historical event). A scenario spec carries a
source (magnitude, fault geometry, hypocenter) and a
stations list (lon/lat/id/Vs30). Returns 202 Accepted with a job reference whose links point to its status, events, and artifacts.
mode: "comparison" requires uploaded observed files and must be sent to
POST /jobs/comparison (multipart) — posting it here returns 422.{
"id": "job_a1b2c3d4e5f6a7b8c9d0",
"status": "queued",
"mode": "scenario",
"method": "GP",
"name": "M6.4 test at Ridgecrest",
"bbp_version": "22.4.0",
"region": "LABasin500",
"realizations_total": 1,
"created_at": "2026-08-01T18:30:00Z",
"links": {
"self": "/v1/jobs/job_a1b2c3d4e5f6a7b8c9d0",
"events": "/v1/jobs/job_a1b2c3d4e5f6a7b8c9d0/events",
"artifacts": "/v1/jobs/job_a1b2c3d4e5f6a7b8c9d0/artifacts"
}
}
POST
/jobs/comparison
Runs a scenario simulation and the BBP goodness-of-fit chain against
your uploaded observed acceleration. This is a multipart/form-data request:
a spec form field (the ComparisonJobSpec JSON, mode: "comparison") plus one BBP-format observed file per station.
observed, and the
station id lives in the filename — <station-id>.bbp. Each file's id
must match a stations[].id in the spec, one-to-one (no missing, no extra), or the
request returns 422. Using per-station field names instead of the filename fails as "no files sent".{
"id": "job_9f8e7d6c5b4a39281706",
"status": "queued",
"mode": "comparison",
"method": "GP",
"name": "Ridgecrest GoF",
"bbp_version": "22.4.0",
"region": "LABasin500",
"realizations_total": 1,
"created_at": "2026-08-01T18:31:00Z",
"links": { "self": "...", "events": "...", "artifacts": "..." }
}
POST
/jobs
Runs the SW4 finite-difference code on a layered 1D crust (the velocity model of a BBP region) and returns low-frequency, band-limited velocity: seismograms at the sites you list, and the motion of the ground surface as frames for movies. It complements BBP's broadband seismograms; it does not replace them.
The rupture usually comes from a finished BBP job of yours
(source.kind: "from_job"), so the two share one source and one velocity model, and
velocity_model.region may be left out. To use your own rupture, send an SRF file to
POST /jobs/sw4 below.
products.site_motions.stations: every site you will want, up tomax_sites. Sites cannot be added after the run, and listing many costs little. A site outside the domain is refused unless"outside_domain": "drop".resolution: grid spacing h =vs_min/ (f_max×points_per_wavelength), rounded onto the supported ladder, or an explicith_m.compute.max_cost_usd: the job is refused (over_max_cost) if the upper bound of its estimate exceeds this.POST /jobs/estimatetakes the same body and returns a modelled runtime and cost with a range.- An event too large for one machine is refused at submit (422
domain_too_largeordeck_too_large), before any compute. Submitting needs the same approval as BBP jobs.
Progress arrives on the job's events stream as job.stage
events: deck, solve (with a percentage), derive,
publish. A spot instance reclaimed mid-run is retried from the start on demand, so the job shows a
second job.running. GET /jobs/{job_id} adds a validation.sw4
block: the grid facts and checks run on the result.
Artifact types:
| seismogram_vel, seismogram_acc | Per site, BBP four-column text (time, N-S, E-W, U-D), band-limited to f_max |
| seismogram_sw4 | Per site, SW4's own output |
| peaks | Peak values per site |
| surface_frames | The surface wavefield as chunked HDF5 (north, east, up velocity), kept keep_days (default 14), then deleted |
| wavefield_manifest | JSON describing the frames: grid, projection, times, scale, band |
| pgv_map | Peak surface velocity as a PNG, and the peak grid with lon/lat bounds (.npz) |
| srf, sw4_input, log | The rupture used, the generated SW4 input, the run log |
The service does not make movies; render them from surface_frames.
POST
/jobs/sw4
The same SW4 job with source.kind: "srf_upload": send the
spec as the spec form field and an SRF file (version 1 or 2) as srf.
velocity_model.region is required, from GET /catalog/regions. A file over the
max_srf_mb limit is refused with 413 srf_too_large.
GET
/jobs
Returns your account's jobs, newest first. Optional query params:
status (e.g. succeeded) and limit (default 50, max 200).
{
"data": [
{
"id": "job_a1b2c3d4e5f6a7b8c9d0",
"status": "succeeded",
"mode": "scenario",
"method": "GP",
"region": "LABasin500",
"realizations_total": 1,
"realizations_succeeded": 1,
"created_at": "2026-08-01T18:30:00Z",
"usage": { "compute_seconds": 512.4, "artifacts_bytes": 8734512 }
}
],
"next_cursor": null
}
GET
/jobs/{job_id}
Full detail for one job: status, realization counts, timestamps, and the
usage rollup (compute-seconds and artifact bytes; estimated: true until the job is terminal). Poll this to await completion.
{
"id": "job_a1b2c3d4e5f6a7b8c9d0",
"status": "succeeded",
"mode": "scenario",
"method": "GP",
"region": "LABasin500",
"realizations_total": 1,
"realizations_succeeded": 1,
"realizations_failed": 0,
"started_at": "2026-08-01T18:30:05Z",
"finished_at": "2026-08-01T18:38:37Z",
"usage": { "compute_seconds": 512.4, "artifacts_bytes": 8734512, "estimated": false },
"error": null,
"links": { "self": "...", "events": "...", "artifacts": "..." }
}
POST
/jobs/{job_id}/cancel
Cancels a job that has not yet started running. Returns 409 if the job is
already terminal (succeeded, failed, or canceled).
GET
/jobs/{job_id}/realizations
Lists each stochastic realization in the job with its seed, status, and compute time — useful for multi-realization runs.
{
"data": [
{ "name": "r0", "seed": 2379646, "sim_id": 5551212, "status": "succeeded", "compute_seconds": 512.4, "error": null }
]
}
GET
/jobs/{job_id}/events
Returns the job's progress event log. By default a JSON snapshot; add
?stream=true to receive a live server-sent events (SSE) stream that
pushes new events until the job finishes — the low-latency way to await completion instead of polling.
{
"data": [
{ "id": 1, "type": "job.started", "created_at": "2026-08-01T18:30:05Z", "data": { } },
{ "id": 2, "type": "job.succeeded", "created_at": "2026-08-01T18:38:37Z", "data": { } }
]
}
Artifacts
A finished job produces downloadable outputs — seismograms, response spectra, goodness-of-fit summaries, plots. List them, then fetch a short-lived signed download URL for each.
GET
/jobs/{job_id}/artifacts
Lists the job's output files with type, station id, size, checksum, and an
expires_at (retention window). Each carries a links object for fetching a signed URL.
{
"data": [
{
"id": "art_1122334455",
"type": "acc_bbp",
"realization": "r0",
"filename": "CLC.acc.bbp",
"station_id": "CLC",
"size_bytes": 204812,
"checksum_sha256": "3f9c...e21a",
"created_at": "2026-08-01T18:38:37Z",
"expires_at": "2026-08-31T18:38:37Z",
"links": { "self": "/v1/artifacts/art_1122334455" }
}
]
}
GET
/artifacts/{artifact_id}
Returns one artifact's metadata plus a download_url (short-lived,
signed) and its expiry. Follow the URL to fetch the file bytes.
{
"id": "art_1122334455",
"type": "acc_bbp",
"filename": "CLC.acc.bbp",
"station_id": "CLC",
"size_bytes": 204812,
"download_url": "https://bbpservices.net/v1/download?...signature...",
"download_url_expires_at": "2026-08-01T19:38:37Z"
}
POST
/jobs/{job_id}/bundle
Packages all of a job's artifacts into a single downloadable archive and returns it as a new artifact (201 Created), so you can pull an entire run in one download.
GET
/download
Serves the artifact file bytes. You do not construct this URL yourself —
use the download_url returned by GET /artifacts/{id}, which carries a signature and expiry.
Usage
GET
/usage
Returns your account's consumption rollup: total compute-seconds, stored
artifact bytes, and job counts. Optional since (ISO 8601) bounds the window by job creation time.
The cost block prices the same window from the rate table
POST /jobs/estimate quotes against, split by_engine (bbp,
sw4) and by instance type and market; rate_basis shows the rates used. Dollar amounts are rounded half up to the cent; usage is metered at full resolution, so a window that cost less than half a cent reads 0.0.
{
"data": {
"jobs": 3,
"compute_seconds": 1620.7,
"artifacts_bytes": 26103544,
"realizations_succeeded": 3,
"jobs_failed": 0,
"cost": {
"currency": "USD",
"compute_usd": 0.62,
"storage_usd": 0.0,
"total_usd": 0.62,
"by_engine": {
"bbp": { "instance_seconds": 28.4, "compute_usd": 0.0 },
"sw4": { "instance_seconds": 716.1, "compute_usd": 0.61 }
},
...
}
}
}
This reference documents account-scoped endpoints only. Administrative endpoints are not part of the public API.