Workflows Endpoint

The Workflows API provides access to workflow and run data.

List Workflows

Get all workflows for your organization(s).

GET /api/v1/dashboard/workflows

Query Parameters

Parameter	Type	Required	Description
org_id	UUID	Yes	Organization ID
days	integer	No	Time range in days (default: 30)
repo	string	No	Filter by repository
status	string	No	Filter by status
limit	integer	No	Max results (1-100). Default: 50

Example Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.cicosts.dev/api/v1/dashboard/workflows?org_id=your-org-id&days=30"

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": "2025-01-15T11:30:00Z"
      }
    ]
  },
  "pagination": {
    "total": 15,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Get Workflow Summary

Get summary statistics for all workflows.

GET /api/v1/dashboard/workflows/summary

Query Parameters

Parameter	Type	Required	Description
org_id	UUID	Yes	Organization ID
days	integer	No	Time range in days (default: 30)

Example Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.cicosts.dev/api/v1/dashboard/workflows/summary?org_id=your-org-id"

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": "2025-01-08", "cost": 156.78},
      {"date": "2025-01-09", "cost": 145.23},
      {"date": "2025-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": "2025-01-15T11:30:00Z",
    "created_at": "2024-06-01T00:00:00Z"
  }
}

Recent Runs

Get recent workflow runs for an organization.

GET /api/v1/dashboard/recent-runs

Query Parameters

Parameter	Type	Required	Description
org_id	UUID	Yes	Organization ID
limit	integer	No	Max results (default: 10)

Example Request

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.cicosts.dev/api/v1/dashboard/recent-runs?org_id=your-org-id&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": "2025-01-15T11:15:00Z",
        "completed_at": "2025-01-15T11:27:30Z"
      }
    ]
  },
  "pagination": {
    "total": 1234,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Run Details

Each run in the response includes detailed job information.

Run Response Fields

Field	Type	Description
id	UUID	Internal run ID
workflow_name	string	Workflow file name (e.g., ci.yml)
repo_name	string	Repository name
github_run_id	integer	GitHub's run ID
status	string	Run status (success, failure, cancelled)
duration_minutes	float	Total runtime in minutes
cost_usd	float	Calculated cost in USD
started_at	datetime	When the run started
completed_at	datetime	When the run completed

Job Details

Each run includes job-level breakdown:

Field	Type	Description
name	string	Job name
runner_label	string	Runner type (e.g., ubuntu-latest)
duration_minutes	float	Job runtime
cost_usd	float	Job cost
status	string	Job status

---

Next: Alerts Endpoint →