Runs API

Monitor and manage agent execution runs through the BambooSnow API.

Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v1/runs | List runs | | GET | /v1/runs/:id | Get run details | | POST | /v1/runs/:id/cancel | Cancel run | | POST | /v1/runs/:id/retry | Retry run | | GET | /v1/runs/:id/logs | Get run logs |

List Runs

GET /v1/runs

Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | agent_id | string | Filter by agent | | repository_id | string | Filter by repository | | status | string | Filter by status | | pr_number | integer | Filter by PR number | | since | datetime | Runs after this time | | until | datetime | Runs before this time | | page | integer | Page number | | per_page | integer | Items per page |

Response

{
  "data": [
    {
      "id": "run_abc123",
      "agent_id": "agent_xyz",
      "agent_name": "code-reviewer",
      "repository": "owner/repo",
      "status": "success",
      "trigger": "pull_request",
      "pr_number": 42,
      "started_at": "2024-01-15T10:30:00Z",
      "completed_at": "2024-01-15T10:30:45Z",
      "duration_ms": 45000,
      "issues_found": 3
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "per_page": 20
  }
}

Get Run Details

GET /v1/runs/:id

Response

{
  "id": "run_abc123",
  "agent": {
    "id": "agent_xyz",
    "name": "code-reviewer",
    "template": "code-reviewer"
  },
  "repository": {
    "id": "repo_123",
    "name": "owner/repo"
  },
  "status": "success",
  "trigger": {
    "type": "pull_request",
    "event": "opened"
  },
  "pull_request": {
    "number": 42,
    "title": "Add user authentication",
    "author": "developer",
    "url": "https://github.com/owner/repo/pull/42"
  },
  "commit": {
    "sha": "abc123...",
    "message": "Implement login flow"
  },
  "started_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:45Z",
  "duration_ms": 45000,
  "results": {
    "summary": "Found 3 issues (0 errors, 2 warnings, 1 info)",
    "issues": [
      {
        "id": "issue_1",
        "severity": "warning",
        "type": "missing_error_handling",
        "file": "src/auth/login.ts",
        "line": 45,
        "message": "Async operation lacks error handling",
        "suggestion": "Add try-catch block"
      }
    ],
    "files_reviewed": 8,
    "lines_analyzed": 450
  },
  "actions_taken": [
    {
      "type": "comment",
      "target": "pull_request",
      "url": "https://github.com/owner/repo/pull/42#issuecomment-123"
    }
  ],
  "tokens_used": {
    "input": 2500,
    "output": 800
  }
}

Run Statuses

| Status | Description | |--------|-------------| | queued | Run is waiting to start | | running | Run is in progress | | success | Run completed successfully | | failure | Run completed with errors | | cancelled | Run was cancelled | | timeout | Run exceeded time limit |

Cancel Run

POST /v1/runs/:id/cancel

Request Body

{
  "reason": "No longer needed"
}

Response

{
  "id": "run_abc123",
  "status": "cancelled",
  "cancelled_at": "2024-01-15T10:31:00Z"
}

Retry Run

POST /v1/runs/:id/retry

Request Body

{
  "config_override": {
    "review_style": "thorough"
  }
}

Response

{
  "original_run_id": "run_abc123",
  "new_run_id": "run_def456",
  "status": "queued"
}

Get Run Logs

GET /v1/runs/:id/logs

Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | level | string | Filter by level (debug, info, warn, error) | | since | datetime | Logs after this time | | limit | integer | Max number of entries |

Response

{
  "run_id": "run_abc123",
  "logs": [
    {
      "timestamp": "2024-01-15T10:30:00.123Z",
      "level": "info",
      "message": "Starting code review",
      "data": {
        "files_count": 8
      }
    },
    {
      "timestamp": "2024-01-15T10:30:05.456Z",
      "level": "info",
      "message": "Analyzing file",
      "data": {
        "file": "src/auth/login.ts"
      }
    },
    {
      "timestamp": "2024-01-15T10:30:45.789Z",
      "level": "info",
      "message": "Review complete",
      "data": {
        "issues_found": 3
      }
    }
  ]
}

Run Statistics

GET /v1/runs/stats

Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | agent_id | string | Filter by agent | | repository_id | string | Filter by repository | | period | string | Time period (day, week, month) |

Response

{
  "period": "week",
  "stats": {
    "total_runs": 156,
    "successful": 150,
    "failed": 6,
    "success_rate": 0.962,
    "avg_duration_ms": 38500,
    "total_issues_found": 423,
    "issues_by_severity": {
      "error": 12,
      "warning": 189,
      "info": 222
    }
  },
  "daily_breakdown": [
    {
      "date": "2024-01-15",
      "runs": 25,
      "successful": 24
    }
  ]
}