GET /api/runs/:runId

Summary

Retrieves a single run by its ID, including its events, current file snapshots, and the previous run’s snapshots for diff comparison.

Intent

Allows clients to fetch the full details of a specific pipeline run, including job metadata, associated events, current file snapshots, and a reference to the previous run for enabling diff views in the UI.

Parameters

Name	Type	Required	Description
runId	string	Yes	The unique identifier of the run to retrieve.
customerId	string	No	Optional query parameter. When provided, the run is only returned if it belongs to this customer; otherwise a 403 is returned.

Request example

curl -X GET "https://maps.google.com/api/runs/run_abc123?customerId=cust_456" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Response example

{
  "run": {
    "jobId": "run_abc123",
    "repoId": "repo_789",
    "customerId": "cust_456",
    "status": "completed",
    "commitSha": "abc123def456",
    "createdAt": "2024-01-15T10:30:00.000Z"
  },
  "events": [
    {
      "eventId": "evt_001",
      "jobId": "run_abc123",
      "type": "job.started",
      "createdAt": "2024-01-15T10:30:01.000Z"
    },
    {
      "eventId": "evt_002",
      "jobId": "run_abc123",
      "type": "job.completed",
      "createdAt": "2024-01-15T10:31:45.000Z"
    }
  ],
  "snapshots": [
    {
      "filePath": "routes/users.ts",
      "jobId": "run_abc123",
      "content": "..."
    }
  ],
  "prevSnapshots": [
    {
      "filePath": "routes/users.ts",
      "jobId": "run_prev_999",
      "content": "..."
    }
  ],
  "prevRunId": "run_prev_999"
}

Error cases

• 404 — No run exists with the given runId
• 403 — A customerId query parameter was provided but does not match the customerId associated with the run

Gotchas

• The customerId query parameter is optional, but if supplied it acts as an ownership check — a mismatch returns 403, not 404, which reveals that the run exists but belongs to a different customer.
• prevSnapshots will be an empty array and prevRunId will be null when there is no previous run for the same repository.
• Runs are ordered by repository (repoId); the ‘previous’ run is determined by listing all jobs for the same repo and finding the one immediately before the current run in that list.
• Although auth is not enforced at the middleware level (auth required: false), the customerId parameter provides a lightweight ownership guard — omitting it returns the run regardless of ownership.