FinOps Schedules

Create and manage resource schedules: daily stop and start times for apps, add-ons, workspaces, and self-hosted models, with pause, resume, run-now, and execution history. See Resource Schedules for how schedules behave.

All endpoints require:

• An API key in the X-API-Key header with the finops:read scope (reads) or the finops:write scope (changes).
• An API key that belongs to a platform administrator. Other keys get 403 forbidden.

Every timestamp is an ISO 8601 UTC instant with a Z offset.

---

Schedule Object

{
  "id": "66f9b2c41d3e8a7f5c2b9e10",
  "name": "Dev weeknight shutdown",
  "description": "Stop the development group overnight and at weekends",
  "organizationId": null,
  "createdBy": "okRpaKPh8B9asdKb2",
  "scope": {
    "type": "resource_group",
    "resourceType": null,
    "resourceId": null,
    "resourceIds": [],
    "tags": {},
    "userId": null,
    "resourceGroupId": "E4k5Ttqk7dtMpwbXx"
  },
  "scopeName": "Development Environment",
  "schedule": {
    "timezone": "America/New_York",
    "stopTime": "19:00",
    "startTime": "08:00",
    "daysOfWeek": [1, 2, 3, 4, 5],
    "stopCron": null,
    "startCron": null
  },
  "enabled": true,
  "status": "active",
  "overrides": [],
  "lastStopAt": "2026-09-28T23:00:00.412871Z",
  "lastStartAt": "2026-09-29T12:00:00.318204Z",
  "nextStopAt": "2026-09-29T23:00:00Z",
  "nextStartAt": "2026-09-30T12:00:00Z",
  "resourcesAffected": [],
  "executionHistory": [
    {
      "action": "start",
      "executedAt": "2026-09-29T12:00:00.318204Z",
      "resourcesAffected": 2,
      "success": true,
      "errorMessage": null,
      "resources": [
        { "resourceType": "app", "resourceId": "hT7kQw2pLm9xRz4vB", "resourceName": "dev-dashboard", "success": true },
        { "resourceType": "addon", "resourceId": "c9Xy3aP0qW8eRt5uN", "resourceName": "dev-postgres", "success": true }
      ]
    }
  ],
  "createdAt": "2026-09-01T16:02:41.284000Z",
  "updatedAt": "2026-09-29T12:00:00.318204Z"
}

Field	Description
id	Schedule ID.
name, description	Name (1 to 100 characters) and optional description (up to 500).
organizationId	null unless one was given at creation. It does not change which resources a platform, user, or resource_group schedule controls.
createdBy	User ID of the administrator who created the schedule.
scope.type	platform (every app, add-on, workspace, and self-hosted model), user (every one the user owns), or resource_group (the group's apps, add-ons, workspaces, and self-hosted models).
scope.user_id	Set for user scope.
scope.resource_group_id	Set for resource_group scope.
scopeName	The user's name or the resource group's name, for user and resource_group scopes; otherwise null.
schedule.timezone	IANA timezone the times are in.
schedule.stop_time, schedule.start_time	HH:MM, 24-hour. Resources stop at stopTime and start at startTime.
schedule.days_of_week	Days the schedule acts on: 1 (Monday) to 7 (Sunday). Both the stop and the start happen on each listed day.
enabled	false when the schedule is paused.
status	active (acts at its times) or paused (does nothing until resumed).
overrides	Resources exempted from the schedule's stops until a given time. This API does not add them.
lastStopAt, lastStartAt	When the schedule last stopped and started its resources, scheduled or run now.
nextStopAt, nextStartAt	When the schedule next stops and starts its resources.
resourcesAffected	Always an empty list; each run's resources are in executionHistory.
execution_history[]	The last 50 runs, oldest first: action (stop or start), executedAt, resourcesAffected (how many resources were stopped or started), success (false when any resource could not be stopped or started), and resources (each resource's resourceType, resourceId, resourceName, and success).
createdAt, updatedAt	When the schedule was created and last changed (including each run).

---

GET /api/v1/finops/schedules

List schedules, newest first.

Scope: finops:read

Query Parameters

Parameter	Type	Required	Description
q	string	No	Case-insensitive match on part of the name
status	string	No	Only schedules with this status: active or paused
scopeType	string	No	Only schedules of this scope: platform, user, or resource_group
enabled	string	No	Only enabled (true) or paused (false) schedules
limit	integer	No	Page size (default 50, maximum 200)
cursor	string	No	meta.nextCursor of the previous page; omit for the first page

Response 200 OK

{
  "data": [
    {
      "id": "66f9b2c41d3e8a7f5c2b9e10",
      "name": "Dev weeknight shutdown",
      "scope": { "type": "resource_group", "resourceGroupId": "E4k5Ttqk7dtMpwbXx" },
      "schedule": { "timezone": "America/New_York", "stopTime": "19:00", "startTime": "08:00", "daysOfWeek": [1, 2, 3, 4, 5] },
      "enabled": true,
      "status": "active"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 50,
    "nextCursor": null,
    "requestId": "783fc8f0-67cb-49cd-829c-90f176be580f"
  }
}

Each item is a full Schedule object (shortened above).

---

POST /api/v1/finops/schedules

Create a schedule. Its creator is the key's user.

Scope: finops:write

Request Body

{
  "name": "Dev weeknight shutdown",
  "description": "Stop the development group overnight and at weekends",
  "scope": { "type": "resource_group", "resourceGroupId": "E4k5Ttqk7dtMpwbXx" },
  "schedule": {
    "timezone": "America/New_York",
    "stopTime": "19:00",
    "startTime": "08:00",
    "daysOfWeek": [1, 2, 3, 4, 5]
  },
  "enabled": true
}

Field	Type	Required	Description
name	string	Yes	Schedule name (1 to 100 characters)
scope	object	Yes	type: platform, user, or resource_group. A user scope also needs userId; a resource_group scope needs resourceGroupId
schedule	object	Yes	timezone (IANA name) and daysOfWeek (1 = Monday to 7 = Sunday) are required; stopTime and startTime are HH:MM, 24-hour
description	string	No	Schedule description (up to 500 characters)
enabled	boolean	No	true (default) creates the schedule active; false creates it paused

Response 201 Created

data is the new Schedule object.

---

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

Get one schedule, with its execution history.

Scope: finops:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Schedule ID

Response 200 OK

data is the full Schedule object.

---

PATCH /api/v1/finops/schedules/:id

Change a schedule. Only the fields you send change. A new schedule recomputes the next stop and start times.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Schedule ID

Request Body

{
  "name": "Dev weeknight shutdown (revised)",
  "schedule": {
    "timezone": "America/New_York",
    "stopTime": "20:00",
    "startTime": "08:00",
    "daysOfWeek": [1, 2, 3, 4, 5]
  }
}

Field	Type	Required	Description
name	string	No	Schedule name
description	string	No	Schedule description
scope	object	No	The whole scope, as for create
schedule	object	No	The whole timing, as for create
enabled	boolean	No	true makes the schedule active, false makes it paused

Response 200 OK

data is the updated Schedule object.

---

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

Delete a schedule permanently. Its resources are left as they are.

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 schedule: it does nothing at its times until it is resumed. Pausing does not start or stop any resources.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Schedule ID

Response 200 OK

The schedule, as GET /finops/schedules/:id shows it, paused.

---

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

Resume a paused schedule, making it active again.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Schedule ID

Response 200 OK

The schedule, as GET /finops/schedules/:id shows it, active again.

---

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

Stop or start the schedule's resources now, whatever its times and whether it is active or paused. The run is recorded in the schedule's execution history.

Scope: finops:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Schedule ID

Request Body

{ "action": "stop" }

Field	Type	Required	Description
action	string	Yes	stop or start

Response 200 OK

{
  "data": {
    "action": "stop",
    "executedAt": "2026-10-11T18:00:00Z",
    "resourcesAffected": 2,
    "success": true,
    "errorMessage": null,
    "resources": [
      { "resourceType": "app", "resourceId": "hT7kQw2pLm9xRz4vB", "resourceName": "dev-dashboard", "success": true },
      { "resourceType": "addon", "resourceId": "c9Xy3aP0qW8eRt5uN", "resourceName": "dev-postgres", "success": true }
    ]
  },
  "meta": { "requestId": "a8e3f1b2-6c4d-4e9f-b0a7-2d5c8e1f3b64" }
}

The run, as the schedule's history records it (the same entry GET .../history lists): resourcesAffected counts the resources that were stopped or started, success is false when any of them could not be (errorMessage says why), and resources has one entry for each resource the run tried, with its success.

---

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

Get a schedule's runs, newest first. The last 50 runs are kept.

Scope: finops:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Schedule ID

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Only the most recent limit runs

Response 200 OK

{
  "data": [
    {
      "action": "start",
      "executedAt": "2026-09-29T12:00:00.318204Z",
      "resourcesAffected": 2,
      "success": true,
      "errorMessage": null,
      "resources": [
        { "resourceType": "app", "resourceId": "hT7kQw2pLm9xRz4vB", "resourceName": "dev-dashboard", "success": true },
        { "resourceType": "addon", "resourceId": "c9Xy3aP0qW8eRt5uN", "resourceName": "dev-postgres", "success": true }
      ]
    }
  ],
  "meta": { "requestId": "0c7b9e2d-4f1a-4b3c-8d6e-9a2f5c1e7b48" }
}

---

MCP tools

The same operations are available to agents as MCP tools: list_finops_schedules, create_finops_schedule, get_finops_schedule, update_finops_schedule, delete_finops_schedule, pause_finops_schedule, resume_finops_schedule, execute_finops_schedule, and get_finops_schedule_history.