Workflows Endpoint

The Workflows API provides access to workflow and run data.

List Workflows

Get all workflows for your organization(s).

GET /v1/workflows

Query Parameters

Parameter	Type	Required	Description
org	string	No	Filter by organization
repo	string	No	Filter by repository
limit	integer	No	Max results (1-100). Default: 50
offset	integer	No	Pagination offset. Default: 0

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.cicosts.dev/v1/workflows?repo=api-service"

Example Response

{
  "data": {
    "workflows": [
      {
        "id": "wf_abc123",
        "name": "ci.yml",
        "path": ".github/workflows/ci.yml",
        "repository": "api-service",
        "organization": "my-company",
        "state": "active",
        "stats": {
          "total_runs": 1234,
          "total_cost": 4567.89,
          "avg_cost_per_run": 3.70,
          "avg_duration_minutes": 12.5,
          "success_rate": 0.94
        },
        "last_run_at": "2024-01-15T11:30:00Z"
      }
    ]
  },
  "pagination": {
    "total": 15,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Get Workflow Details

Get details for a specific workflow.

GET /v1/workflows/:id

Path Parameters

Parameter	Type	Description
id	string	Workflow ID

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.cicosts.dev/v1/workflows/wf_abc123

Example Response

{
  "data": {
    "id": "wf_abc123",
    "name": "ci.yml",
    "path": ".github/workflows/ci.yml",
    "repository": "api-service",
    "organization": "my-company",
    "state": "active",
    "triggers": ["push", "pull_request"],
    "stats": {
      "total_runs": 1234,
      "total_cost": 4567.89,
      "avg_cost_per_run": 3.70,
      "avg_duration_minutes": 12.5,
      "success_rate": 0.94,
      "failure_rate": 0.06
    },
    "cost_trend": [
      {"date": "2024-01-08", "cost": 156.78},
      {"date": "2024-01-09", "cost": 145.23},
      {"date": "2024-01-10", "cost": 167.89}
    ],
    "top_jobs": [
      {"name": "build", "avg_cost": 1.23},
      {"name": "test", "avg_cost": 2.15},
      {"name": "deploy", "avg_cost": 0.32}
    ],
    "last_run_at": "2024-01-15T11:30:00Z",
    "created_at": "2023-06-01T00:00:00Z"
  }
}

List Workflow Runs

Get runs for a specific workflow.

GET /v1/workflows/:id/runs

Path Parameters

Parameter	Type	Description
id	string	Workflow ID

Query Parameters

Parameter	Type	Required	Description
start_date	string	No	Start date (YYYY-MM-DD)
end_date	string	No	End date (YYYY-MM-DD)
status	string	No	Filter: success, failure, cancelled
limit	integer	No	Max results (1-100). Default: 50
offset	integer	No	Pagination offset. Default: 0

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.cicosts.dev/v1/workflows/wf_abc123/runs?status=success&limit=10"

Example Response

{
  "data": {
    "runs": [
      {
        "id": "run_xyz789",
        "workflow_id": "wf_abc123",
        "github_run_id": 12345678,
        "github_run_number": 456,
        "status": "success",
        "conclusion": "success",
        "trigger": "push",
        "branch": "main",
        "commit_sha": "abc123def456",
        "duration_minutes": 12.5,
        "cost": 3.45,
        "jobs": [
          {
            "name": "build",
            "status": "success",
            "runner": "ubuntu-latest",
            "duration_minutes": 5.2,
            "cost": 0.04
          },
          {
            "name": "test",
            "status": "success",
            "runner": "ubuntu-latest-8-core",
            "duration_minutes": 7.3,
            "cost": 0.23
          }
        ],
        "started_at": "2024-01-15T11:15:00Z",
        "completed_at": "2024-01-15T11:27:30Z"
      }
    ]
  },
  "pagination": {
    "total": 1234,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Get Run Details

Get details for a specific workflow run.

GET /v1/runs/:id

Path Parameters

Parameter	Type	Description
id	string	Run ID

Example Response

{
  "data": {
    "id": "run_xyz789",
    "workflow_id": "wf_abc123",
    "workflow_name": "ci.yml",
    "repository": "api-service",
    "organization": "my-company",
    "github_run_id": 12345678,
    "github_run_number": 456,
    "status": "success",
    "conclusion": "success",
    "trigger": "push",
    "branch": "main",
    "commit_sha": "abc123def456",
    "commit_message": "Fix authentication bug",
    "author": "jdoe",
    "duration_minutes": 12.5,
    "billable_minutes": 13,
    "cost": 3.45,
    "jobs": [
      {
        "id": "job_aaa111",
        "name": "build",
        "status": "success",
        "runner": "ubuntu-latest",
        "runner_group": "GitHub Actions",
        "duration_minutes": 5.2,
        "billable_minutes": 6,
        "cost": 0.05,
        "steps": [
          {"name": "Checkout", "duration_seconds": 3},
          {"name": "Setup Node", "duration_seconds": 45},
          {"name": "Install", "duration_seconds": 120},
          {"name": "Build", "duration_seconds": 145}
        ],
        "started_at": "2024-01-15T11:15:00Z",
        "completed_at": "2024-01-15T11:20:12Z"
      }
    ],
    "started_at": "2024-01-15T11:15:00Z",
    "completed_at": "2024-01-15T11:27:30Z"
  }
}

---

Next: Alerts Endpoint →