BBP API Reference

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" }
  ]
}

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)" }
  ]
}

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" }
  ]
}

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"
    }
  ]
}

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.

{
  "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"
  }
}

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.

{
  "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": "..." }
}

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
}

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": "..." }
}

Cancels a job that has not yet started running. Returns 409 if the job is already terminal (succeeded, failed, or canceled).

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 }
  ]
}

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": { } }
  ]
}

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" }
    }
  ]
}

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"
}

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.

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.

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.

{
  "data": {
    "jobs": 3,
    "compute_seconds": 1620.7,
    "artifacts_bytes": 26103544,
    "realizations_succeeded": 3,
    "jobs_failed": 0
  }
}