FinOps Schedules

Schedule automatic budget review cycles, cost reports, and resource-group rollups, including auto-stop/start schedules with pause/resume/execute/history controls.

All endpoints require authentication via X-API-Key header and the appropriate scope.

---

Schedule Object

{
  "_id": "sch_abc123",
  "name": "Nightly auto-stop",
  "description": "Stop dev workspaces every weeknight",
  "scope": {
    "level": "resourceGroup",
    "id": "rg_dev"
  },
  "schedule": {
    "cron": "0 22 * * 1-5",
    "timezone": "America/Los_Angeles",
    "action": "stop"
  },
  "status": "active",
  "enabled": true,
  "createdBy": "user_456",
  "organizationId": "org_xyz",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-02-01T14:22:00Z"
}

---

GET /api/v1/finops/schedules

List resource schedules with pagination, search, status, scope level, and enabled filters.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
search	string	No	Search term for name or description
status	string	No	Filter by schedule status
scopeLevel	string	No	Filter by scope level
enabled	string	No	Filter by enabled state (true or false)
limit	integer	No	Number of results to return
offset	integer	No	Number of results to skip
sort	string	No	Sort field and direction

Response 200 OK

{
  "count": 1,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "_id": "sch_abc123",
      "name": "Nightly auto-stop",
      "status": "active",
      "enabled": true
    }
  ]
}

---

POST /api/v1/finops/schedules

Create a new resource schedule.

Scope: finops:write

Request Body

{
  "name": "Nightly auto-stop",
  "scope": { "level": "resourceGroup", "id": "rg_dev" },
  "schedule": {
    "cron": "0 22 * * 1-5",
    "timezone": "America/Los_Angeles",
    "action": "stop"
  },
  "description": "Stop dev workspaces every weeknight"
}

Field	Type	Required	Description
name	string	Yes	Schedule name
scope	object	Yes	Schedule scope configuration
schedule	object	Yes	Schedule timing configuration
description	string	No	Schedule description

Response 201 Created

{
  "scheduleId": "sch_abc123"
}

---

GET /api/v1/finops/schedules/:id

Get a single resource schedule by ID.

Scope: finops:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Schedule ID

Response 200 OK

Returns the full Schedule object.

---

PUT /api/v1/finops/schedules/:id

Update an existing resource schedule by ID.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Schedule ID

Request Body

{
  "name": "Nightly auto-stop (revised)",
  "schedule": {
    "cron": "0 23 * * 1-5",
    "timezone": "America/Los_Angeles",
    "action": "stop"
  }
}

Field	Type	Required	Description
name	string	No	Schedule name
scope	object	No	Schedule scope configuration
schedule	object	No	Schedule timing configuration
description	string	No	Schedule description

Response 200 OK

Returns the updated Schedule object.

---

DELETE /api/v1/finops/schedules/:id

Delete a resource schedule by ID.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Schedule ID

Response 204 No Content

---

POST /api/v1/finops/schedules/:id/pause

Pause a resource schedule by ID.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Schedule ID

Response 200 OK

{
  "_id": "sch_abc123",
  "status": "paused"
}

---

POST /api/v1/finops/schedules/:id/resume

Resume a paused resource schedule by ID.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Schedule ID

Response 200 OK

{
  "_id": "sch_abc123",
  "status": "active"
}

---

POST /api/v1/finops/schedules/:id/execute

Execute a resource schedule immediately by ID.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Schedule ID

Request Body

Optional body forwarded to the execution call (e.g. override arguments).

Response 200 OK

Returns the immediate execution result.

---

GET /api/v1/finops/schedules/:id/history

Get execution history for a resource schedule by ID.

Scope: finops:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Schedule ID

Response 200 OK

Returns the schedule's execution history records.