Costs Endpoint

The Costs API provides access to your CI/CD cost data.

Get Costs

Retrieve cost data for a time period.

GET /v1/costs

Query Parameters

Parameter	Type	Required	Description
start_date	string	No	Start date (YYYY-MM-DD). Default: 7 days ago
end_date	string	No	End date (YYYY-MM-DD). Default: today
org	string	No	Filter by organization
repo	string	No	Filter by repository
workflow	string	No	Filter by workflow name
granularity	string	No	day, week, or month. Default: day

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.cicosts.dev/v1/costs?start_date=2024-01-01&end_date=2024-01-31"

Example Response

{
  "data": {
    "total_cost": 1847.23,
    "total_runs": 1523,
    "total_minutes": 23456,
    "costs": [
      {
        "date": "2024-01-01",
        "cost": 45.67,
        "runs": 52,
        "minutes": 684
      },
      {
        "date": "2024-01-02",
        "cost": 51.23,
        "runs": 48,
        "minutes": 756
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T12:00:00Z"
  }
}

Get Cost Summary

Get a high-level cost summary.

GET /v1/costs/summary

Query Parameters

Parameter	Type	Required	Description
org	string	No	Filter by organization

Example Request

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

Example Response

{
  "data": {
    "today": {
      "cost": 47.82,
      "runs": 23,
      "change_pct": 12.5
    },
    "this_week": {
      "cost": 312.50,
      "runs": 156,
      "change_pct": 5.2
    },
    "this_month": {
      "cost": 1247.00,
      "runs": 623,
      "change_pct": -8.1
    },
    "projected": {
      "cost": 1890.00,
      "based_on": "current_trend"
    }
  }
}

Get Costs by Repository

Get costs broken down by repository.

GET /v1/costs/by-repository

Query Parameters

Parameter	Type	Required	Description
start_date	string	No	Start date (YYYY-MM-DD)
end_date	string	No	End date (YYYY-MM-DD)
org	string	No	Filter by organization
limit	integer	No	Max results. Default: 20

Example Response

{
  "data": {
    "repositories": [
      {
        "name": "api-service",
        "org": "my-company",
        "cost": 892.45,
        "runs": 456,
        "pct_of_total": 48.3
      },
      {
        "name": "web-app",
        "org": "my-company",
        "cost": 523.12,
        "runs": 312,
        "pct_of_total": 28.3
      }
    ]
  }
}

Get Costs by Workflow

Get costs broken down by workflow.

GET /v1/costs/by-workflow

Query Parameters

Parameter	Type	Required	Description
start_date	string	No	Start date (YYYY-MM-DD)
end_date	string	No	End date (YYYY-MM-DD)
org	string	No	Filter by organization
repo	string	No	Filter by repository
limit	integer	No	Max results. Default: 20

Example Response

{
  "data": {
    "workflows": [
      {
        "name": "ci.yml",
        "repository": "api-service",
        "cost": 456.78,
        "runs": 234,
        "avg_cost": 1.95,
        "avg_duration_minutes": 8.5
      },
      {
        "name": "deploy.yml",
        "repository": "api-service",
        "cost": 234.56,
        "runs": 89,
        "avg_cost": 2.64,
        "avg_duration_minutes": 12.3
      }
    ]
  }
}

Export Costs

Export cost data in CSV or JSON format.

GET /v1/costs/export

Query Parameters

Parameter	Type	Required	Description
start_date	string	Yes	Start date (YYYY-MM-DD)
end_date	string	Yes	End date (YYYY-MM-DD)
format	string	No	csv or json. Default: csv
granularity	string	No	summary, daily, per-run, per-job
org	string	No	Filter by organization
repo	string	No	Filter by repository

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.cicosts.dev/v1/costs/export?start_date=2024-01-01&end_date=2024-01-31&format=csv" \
  -o costs.csv

CSV Response

date,repository,workflow,runs,total_cost,avg_cost
2024-01-15,api-service,ci.yml,45,123.45,2.74
2024-01-15,web-app,tests.yml,32,89.00,2.78

JSON Response

{
  "data": {
    "export_date": "2024-01-15T12:00:00Z",
    "date_range": {
      "start": "2024-01-01",
      "end": "2024-01-31"
    },
    "rows": [
      {
        "date": "2024-01-15",
        "repository": "api-service",
        "workflow": "ci.yml",
        "runs": 45,
        "total_cost": 123.45,
        "avg_cost": 2.74
      }
    ]
  }
}

---

Next: Workflows Endpoint →