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:

Authorization: Bearer <your-api-key>

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.

Base URL: 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.

Map of the five SCEC Broadband Platform velocity-model regions across California: NoCal, CenCoast, Southern Sierra Nevada, Mojave and SoCal
The five California velocity-model regions. A location outside every region can still be simulated against the nearest one, as a labelled approximation. Each region has more than one name. The labels on this map are the regional names used in the SCEC literature. The API identifies a region by its package id, which is what you pass as 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.

curl "https://bbpservices.net/v1/catalog/methods" \ -H "Authorization: Bearer <your-api-key>"
{
  "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.

curl "https://bbpservices.net/v1/catalog/regions" \ -H "Authorization: Bearer <your-api-key>"
{
  "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.

curl "https://bbpservices.net/v1/catalog/validation-events" \ -H "Authorization: Bearer <your-api-key>"
{
  "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.

curl "https://bbpservices.net/v1/catalog/versions" \ -H "Authorization: Bearer <your-api-key>"
{
  "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.

curl "https://bbpservices.net/v1/catalog/engines" \ -H "Authorization: Bearer <your-api-key>"
{
  "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.

Comparison jobs go elsewhere. mode: "comparison" requires uploaded observed files and must be sent to POST /jobs/comparison (multipart) — posting it here returns 422.
curl -X POST "https://bbpservices.net/v1/jobs" \ -H "Authorization: Bearer <your-api-key>" \ -H "Content-Type: application/json" \ -d '{ "mode": "scenario", "name": "M6.4 test at Ridgecrest", "method": "GP", "region": "LABasin500", "source": { "magnitude": 6.4, "fault_length": 15.0, "fault_width": 12.0, "depth_to_top": 1.0, "strike": 227, "rake": -173, "dip": 89, "lat_top_center": 35.705, "lon_top_center": -117.504, "hypo_along_strike": 0.0, "hypo_down_dip": 6.0 }, "stations": [ { "lon": -117.67, "lat": 35.77, "id": "CLC", "vs30": 350 } ], "realizations": { "count": 1 } }'
{
  "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.

File-naming contract (easy to get wrong): every observed file is uploaded under the same field name 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".
curl -X POST "https://bbpservices.net/v1/jobs/comparison" \ -H "Authorization: Bearer <your-api-key>" \ -F 'spec={"mode":"comparison","name":"Ridgecrest GoF","event_id":"ci38457511","method":"GP","region":"LABasin500","source":{...},"stations":[{"lon":-117.67,"lat":35.77,"id":"CLC","vs30":350}]};type=application/json' \ -F "observed=@CLC.bbp"
{
  "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 to max_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 explicit h_m.
  • compute.max_cost_usd: the job is refused (over_max_cost) if the upper bound of its estimate exceeds this. POST /jobs/estimate takes 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_large or deck_too_large), before any compute. Submitting needs the same approval as BBP jobs.
curl -X POST "https://bbpservices.net/v1/jobs" \ -H "Authorization: Bearer <your-api-key>" \ -H "Content-Type: application/json" \ -d '{ "mode": "sw4", "name": "La Habra M5.1 SW4", "source": { "kind": "from_job", "job_id": "job_d8287cd897f647acb135", "realization": 1 }, "velocity_model": { "kind": "bbp_1d", "vs_min": 500 }, "resolution": { "f_max": 0.5, "points_per_wavelength": 5 }, "domain": { "auto": { "margin_km": 5, "include": ["fault", "site_motions"], "max_extent_km": 200 } }, "duration_s": 40, "products": { "site_motions": { "stations": [ { "id": "CI.PSR", "lat": 33.925, "lon": -117.891, "depth_m": 0 } ] }, "wavefield": { "frames": { "dt_s": 0.2, "keep_days": 14 }, "pgv_map": true } }, "compute": { "priority": "standard", "max_cost_usd": 15.0 } }'

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_accPer site, BBP four-column text (time, N-S, E-W, U-D), band-limited to f_max
seismogram_sw4Per site, SW4's own output
peaksPeak values per site
surface_framesThe surface wavefield as chunked HDF5 (north, east, up velocity), kept keep_days (default 14), then deleted
wavefield_manifestJSON describing the frames: grid, projection, times, scale, band
pgv_mapPeak surface velocity as a PNG, and the peak grid with lon/lat bounds (.npz)
srf, sw4_input, logThe 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.

curl -X POST "https://bbpservices.net/v1/jobs/sw4" \ -H "Authorization: Bearer <your-api-key>" \ -F 'spec={"mode": "sw4", "name": "Northridge SRF", "source": {"kind": "srf_upload"}, "velocity_model": {"kind": "bbp_1d", "region": "LABasin500", "vs_min": 500}, ...}' \ -F "srf=@northridge.srf"
GET /jobs

Returns your account's jobs, newest first. Optional query params: status (e.g. succeeded) and limit (default 50, max 200).

curl "https://bbpservices.net/v1/jobs?status=succeeded&limit=20" \ -H "Authorization: Bearer <your-api-key>"
{
  "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.

curl "https://bbpservices.net/v1/jobs/job_a1b2c3d4e5f6a7b8c9d0" \ -H "Authorization: Bearer <your-api-key>"
{
  "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).

curl -X POST "https://bbpservices.net/v1/jobs/job_a1b2c3d4e5f6a7b8c9d0/cancel" \ -H "Authorization: Bearer <your-api-key>"
GET /jobs/{job_id}/realizations

Lists each stochastic realization in the job with its seed, status, and compute time — useful for multi-realization runs.

curl "https://bbpservices.net/v1/jobs/job_a1b2c3d4e5f6a7b8c9d0/realizations" \ -H "Authorization: Bearer <your-api-key>"
{
  "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.

curl "https://bbpservices.net/v1/jobs/job_a1b2c3d4e5f6a7b8c9d0/events?stream=true" \ -H "Authorization: Bearer <your-api-key>"
{
  "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.

curl "https://bbpservices.net/v1/jobs/job_a1b2c3d4e5f6a7b8c9d0/artifacts" \ -H "Authorization: Bearer <your-api-key>"
{
  "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.

curl "https://bbpservices.net/v1/artifacts/art_1122334455" \ -H "Authorization: Bearer <your-api-key>"
{
  "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.

curl -X POST "https://bbpservices.net/v1/jobs/job_a1b2c3d4e5f6a7b8c9d0/bundle" \ -H "Authorization: Bearer <your-api-key>"
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.

curl -L -o CLC.acc.bbp \ "https://bbpservices.net/v1/download?...signature..."

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.

curl "https://bbpservices.net/v1/usage?since=2026-08-01T00:00:00Z" \ -H "Authorization: Bearer <your-api-key>"
{
  "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.