If the API is called with a Personal API token, the user must be a member of the specified stack.
If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.

header

true

integer

id ID of the load test. path true integer

`200` response

OK.

Content types: `application/json`

ScheduleApiModel properties:

Name	Description	Required	Type
`created_by`	The email of the user who created the schedule if applicable.	`true`	`string` \| `null`
`deactivated`	Whether the schedule is deactivated. A deactivated schedule will not trigger new test runs, but the schedule recurrence rule and expiration is not affected.	`true`	`boolean`
`id`	ID of the schedule.	`true`	`integer`
`load_test_id`	ID of the test to run.	`true`	`integer`
`next_run`	The date of the next scheduled test run. The value is `null` if the schedule is expired and no more occurrences are expected in the future according to the recurrence rule.	`true`	`string` \| `null` , format: `date-time`
`recurrence_rule`	The schedule recurrence settings. If null, the test will run only once on the `starts` date.	`true`	`ScheduleRecurrenceRule` \| `null`
`starts`	The date on which the schedule will start running the test.	`true`	`string` , format: `date-time`

ScheduleRecurrenceRule properties:

Name	Description	Required	Type
`byday`	The weekdays when the ‘WEEKLY’ recurrence will be applied. Cannot be set for other frequencies.	`false`	`array` \| `null`
`count`	Determines how many times the recurrence will repeat.	`false`	`integer` \| `null`
`frequency`		`true`	`Frequency`
`interval`	The interval between each frequency iteration. An interval of 2 with ‘HOURLY’ frequency makes the test run once every 2 hours.	`false`	`integer`
`until`	A datetime instance specifying the upper-bound time limit of the recurrence.	`false`	`string` \| `null` , format: `date-time`

The unit type of the recurrence interval.

Deactivated example

{
  "created_by": "user@example.com",
  "deactivated": true,
  "id": 123,
  "load_test_id": 234,
  "next_run": "2024-07-20T01:46:04.021Z",
  "recurrence_rule": {
    "days": [],
    "ends": null,
    "frequency": "HOURLY",
    "interval": 2
  },
  "starts": "2024-07-16T08:46:04.021Z"
}

EveryTwoHours example

{
  "created_by": "user@example.com",
  "deactivated": false,
  "id": 123,
  "load_test_id": 234,
  "next_run": "2024-07-20T01:46:04.021Z",
  "recurrence_rule": {
    "byday": null,
    "count": null,
    "frequency": "HOURLY",
    "interval": 2,
    "until": null
  },
  "starts": "2024-07-16T08:46:04.021Z"
}

TriggeredOnceInThePast example

{
  "created_by": "user@example.com",
  "deactivated": false,
  "id": 123,
  "load_test_id": 234,
  "next_run": null,
  "recurrence_rule": null,
  "starts": "2023-08-01T12:00:00.000Z"
}

WeeklyOnWeekendsStopsAfter10Runs example

{
  "created_by": null,
  "deactivated": false,
  "id": 123,
  "load_test_id": 234,
  "next_run": "2024-07-17T08:46:04.021Z",
  "recurrence_rule": {
    "byday": [
      "SA",
      "SU"
    ],
    "count": 10,
    "frequency": "WEEKLY",
    "interval": 1,
    "until": null
  },
  "starts": "2024-07-16T08:46:04.021Z"
}

`401` response

`403` response

`404` response

`500` response

Set a schedule for the load test

POST /cloud/v6/load_tests/{id}/schedule

Set a schedule for the load test.

This operation overwrites any existing test schedule.

Monthly schedules running on days 29-31 are adjusted to run on the last day of the month if the target day doesn’t exist in a given month (for example, March 31 -> April 30).

Request parameters

Name Description In Required Type

X-Stack-Id

Numeric ID of the Grafana stack representing the request scope.

If the API is called with a Personal API token, the user must be a member of the specified stack.
If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.

header

true

integer

id ID of the load test. path true integer

Request body

Content types: `application/json`

CreateScheduleRequest properties:

Name	Description	Required	Type
`recurrence_rule`	The schedule recurrence settings. If null, the test will run only once on the `starts` date.	`true`	`ScheduleRecurrenceRule` \| `null`
`starts`	The timezone-aware date on which the schedule will start running the test.	`true`	`string` , format: `date-time`

ScheduleRecurrenceRule properties:

Name	Description	Required	Type
`byday`	The weekdays when the ‘WEEKLY’ recurrence will be applied. Cannot be set for other frequencies.	`false`	`array` \| `null`
`count`	Determines how many times the recurrence will repeat.	`false`	`integer` \| `null`
`frequency`		`true`	`Frequency`
`interval`	The interval between each frequency iteration. An interval of 2 with ‘HOURLY’ frequency makes the test run once every 2 hours.	`false`	`integer`
`until`	A datetime instance specifying the upper-bound time limit of the recurrence.	`false`	`string` \| `null` , format: `date-time`

The unit type of the recurrence interval.

EveryTwoHours example

{
  "recurrence_rule": {
    "frequency": "HOURLY",
    "interval": 2
  },
  "starts": "2024-07-16T08:46:04.021Z"
}

TriggeredOnce example

{
  "recurrence_rule": null,
  "starts": "2028-08-01T12:00:00.000Z"
}

WeeklyOnWeekendsStopsAfter10Runs example

{
  "recurrence_rule": {
    "byday": [
      "SA",
      "SU"
    ],
    "count": 10,
    "frequency": "WEEKLY"
  },
  "starts": "2024-07-16T08:46:04.021Z"
}

`200` response

OK.

Content types: `application/json`

ScheduleApiModel properties:

Name	Description	Required	Type
`created_by`	The email of the user who created the schedule if applicable.	`true`	`string` \| `null`
`deactivated`	Whether the schedule is deactivated. A deactivated schedule will not trigger new test runs, but the schedule recurrence rule and expiration is not affected.	`true`	`boolean`
`id`	ID of the schedule.	`true`	`integer`
`load_test_id`	ID of the test to run.	`true`	`integer`
`next_run`	The date of the next scheduled test run. The value is `null` if the schedule is expired and no more occurrences are expected in the future according to the recurrence rule.	`true`	`string` \| `null` , format: `date-time`
`recurrence_rule`	The schedule recurrence settings. If null, the test will run only once on the `starts` date.	`true`	`ScheduleRecurrenceRule` \| `null`
`starts`	The date on which the schedule will start running the test.	`true`	`string` , format: `date-time`

ScheduleRecurrenceRule properties:

Name	Description	Required	Type
`byday`	The weekdays when the ‘WEEKLY’ recurrence will be applied. Cannot be set for other frequencies.	`false`	`array` \| `null`
`count`	Determines how many times the recurrence will repeat.	`false`	`integer` \| `null`
`frequency`		`true`	`Frequency`
`interval`	The interval between each frequency iteration. An interval of 2 with ‘HOURLY’ frequency makes the test run once every 2 hours.	`false`	`integer`
`until`	A datetime instance specifying the upper-bound time limit of the recurrence.	`false`	`string` \| `null` , format: `date-time`

The unit type of the recurrence interval.

Deactivated example

{
  "created_by": "user@example.com",
  "deactivated": true,
  "id": 123,
  "load_test_id": 234,
  "next_run": "2024-07-20T01:46:04.021Z",
  "recurrence_rule": {
    "days": [],
    "ends": null,
    "frequency": "HOURLY",
    "interval": 2
  },
  "starts": "2024-07-16T08:46:04.021Z"
}

EveryTwoHours example

{
  "created_by": "user@example.com",
  "deactivated": false,
  "id": 123,
  "load_test_id": 234,
  "next_run": "2024-07-20T01:46:04.021Z",
  "recurrence_rule": {
    "byday": null,
    "count": null,
    "frequency": "HOURLY",
    "interval": 2,
    "until": null
  },
  "starts": "2024-07-16T08:46:04.021Z"
}

TriggeredOnceInThePast example

{
  "created_by": "user@example.com",
  "deactivated": false,
  "id": 123,
  "load_test_id": 234,
  "next_run": null,
  "recurrence_rule": null,
  "starts": "2023-08-01T12:00:00.000Z"
}

WeeklyOnWeekendsStopsAfter10Runs example

{
  "created_by": null,
  "deactivated": false,
  "id": 123,
  "load_test_id": 234,
  "next_run": "2024-07-17T08:46:04.021Z",
  "recurrence_rule": {
    "byday": [
      "SA",
      "SU"
    ],
    "count": 10,
    "frequency": "WEEKLY",
    "interval": 1,
    "until": null
  },
  "starts": "2024-07-16T08:46:04.021Z"
}

`400` response

`401` response

`403` response

`404` response

`500` response

List all schedules

GET /cloud/v6/schedules

List all schedules.

Request parameters

Name	Description	In	Required	Type
`X-Stack-Id`	Numeric ID of the Grafana stack representing the request scope. If the API is called with a Personal API token, the user must be a member of the specified stack. If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.	`header`	`true`	`integer`
`$count`	Include collection length in the response object as `@count`.	`query`	`false`	`boolean`
`$skip`	The initial index from which to return the results.	`query`	`false`	`integer`
`$top`	Number of results to return per page. Default: `1000` Maximum: `1000`	`query`	`false`	`integer`

`200` response

OK.

Content types: `application/json`

ScheduleListResponse properties:

Name	Description	Required	Type
`@count`	Object count in the collection.	`false`	`integer`
`@nextLink`	A reference to the next page of results. The property is included until there are no more pages of results to retrieve.	`false`	`string` , format: `uri`
`value`	List of the resulting values.	`true`	`Array[ScheduleApiModel]`

ScheduleApiModel properties:

Name	Description	Required	Type
`created_by`	The email of the user who created the schedule if applicable.	`true`	`string` \| `null`
`deactivated`	Whether the schedule is deactivated. A deactivated schedule will not trigger new test runs, but the schedule recurrence rule and expiration is not affected.	`true`	`boolean`
`id`	ID of the schedule.	`true`	`integer`
`load_test_id`	ID of the test to run.	`true`	`integer`
`next_run`	The date of the next scheduled test run. The value is `null` if the schedule is expired and no more occurrences are expected in the future according to the recurrence rule.	`true`	`string` \| `null` , format: `date-time`
`recurrence_rule`	The schedule recurrence settings. If null, the test will run only once on the `starts` date.	`true`	`ScheduleRecurrenceRule` \| `null`
`starts`	The date on which the schedule will start running the test.	`true`	`string` , format: `date-time`

ScheduleRecurrenceRule properties:

Name	Description	Required	Type
`byday`	The weekdays when the ‘WEEKLY’ recurrence will be applied. Cannot be set for other frequencies.	`false`	`array` \| `null`
`count`	Determines how many times the recurrence will repeat.	`false`	`integer` \| `null`
`frequency`		`true`	`Frequency`
`interval`	The interval between each frequency iteration. An interval of 2 with ‘HOURLY’ frequency makes the test run once every 2 hours.	`false`	`integer`
`until`	A datetime instance specifying the upper-bound time limit of the recurrence.	`false`	`string` \| `null` , format: `date-time`

The unit type of the recurrence interval.

OK example

{
  "@count": 12,
  "@nextLink": "https://api.k6.io/cloud/v6/schedules?$skip=50\u0026$top=20",
  "value": [
    {
      "created_by": "user@example.com",
      "deactivated": false,
      "id": 123,
      "load_test_id": 234,
      "next_run": "2024-07-20T01:46:04.021Z",
      "recurrence_rule": {
        "byday": null,
        "count": null,
        "frequency": "HOURLY",
        "interval": 2,
        "until": null
      },
      "starts": "2024-07-16T08:46:04.021Z"
    }
  ]
}

`400` response

`401` response

`403` response

`500` response

Get a schedule by ID

GET /cloud/v6/schedules/{id}

Get a schedule by ID.

Request parameters

Name Description In Required Type

X-Stack-Id

Numeric ID of the Grafana stack representing the request scope.

If the API is called with a Personal API token, the user must be a member of the specified stack.
If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.

header

true

integer

id ID of the schedule. path true integer

`200` response

OK.

Content types: `application/json`

ScheduleApiModel properties:

Name	Description	Required	Type
`created_by`	The email of the user who created the schedule if applicable.	`true`	`string` \| `null`
`deactivated`	Whether the schedule is deactivated. A deactivated schedule will not trigger new test runs, but the schedule recurrence rule and expiration is not affected.	`true`	`boolean`
`id`	ID of the schedule.	`true`	`integer`
`load_test_id`	ID of the test to run.	`true`	`integer`
`next_run`	The date of the next scheduled test run. The value is `null` if the schedule is expired and no more occurrences are expected in the future according to the recurrence rule.	`true`	`string` \| `null` , format: `date-time`
`recurrence_rule`	The schedule recurrence settings. If null, the test will run only once on the `starts` date.	`true`	`ScheduleRecurrenceRule` \| `null`
`starts`	The date on which the schedule will start running the test.	`true`	`string` , format: `date-time`

ScheduleRecurrenceRule properties:

Name	Description	Required	Type
`byday`	The weekdays when the ‘WEEKLY’ recurrence will be applied. Cannot be set for other frequencies.	`false`	`array` \| `null`
`count`	Determines how many times the recurrence will repeat.	`false`	`integer` \| `null`
`frequency`		`true`	`Frequency`
`interval`	The interval between each frequency iteration. An interval of 2 with ‘HOURLY’ frequency makes the test run once every 2 hours.	`false`	`integer`
`until`	A datetime instance specifying the upper-bound time limit of the recurrence.	`false`	`string` \| `null` , format: `date-time`

The unit type of the recurrence interval.

Deactivated example

{
  "created_by": "user@example.com",
  "deactivated": true,
  "id": 123,
  "load_test_id": 234,
  "next_run": "2024-07-20T01:46:04.021Z",
  "recurrence_rule": {
    "days": [],
    "ends": null,
    "frequency": "HOURLY",
    "interval": 2
  },
  "starts": "2024-07-16T08:46:04.021Z"
}

EveryTwoHours example

{
  "created_by": "user@example.com",
  "deactivated": false,
  "id": 123,
  "load_test_id": 234,
  "next_run": "2024-07-20T01:46:04.021Z",
  "recurrence_rule": {
    "byday": null,
    "count": null,
    "frequency": "HOURLY",
    "interval": 2,
    "until": null
  },
  "starts": "2024-07-16T08:46:04.021Z"
}

TriggeredOnceInThePast example

{
  "created_by": "user@example.com",
  "deactivated": false,
  "id": 123,
  "load_test_id": 234,
  "next_run": null,
  "recurrence_rule": null,
  "starts": "2023-08-01T12:00:00.000Z"
}

WeeklyOnWeekendsStopsAfter10Runs example

{
  "created_by": null,
  "deactivated": false,
  "id": 123,
  "load_test_id": 234,
  "next_run": "2024-07-17T08:46:04.021Z",
  "recurrence_rule": {
    "byday": [
      "SA",
      "SU"
    ],
    "count": 10,
    "frequency": "WEEKLY",
    "interval": 1,
    "until": null
  },
  "starts": "2024-07-16T08:46:04.021Z"
}

`401` response

`403` response

`404` response

`500` response

Delete a schedule

DELETE /cloud/v6/schedules/{id}

Delete a schedule.

Request parameters

Name Description In Required Type

X-Stack-Id

Numeric ID of the Grafana stack representing the request scope.

If the API is called with a Personal API token, the user must be a member of the specified stack.
If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.

header

true

integer

id ID of the schedule. path true integer

`204` response

OK.

`401` response

`403` response

`404` response

`500` response

Re-activate deactivated schedule

POST /cloud/v6/schedules/{id}/activate

Re-activate a deactivated schedule.

A deactivated schedule can be re-activated only if it still has at least one future recurrence.

Request parameters

Name Description In Required Type

X-Stack-Id

Numeric ID of the Grafana stack representing the request scope.

If the API is called with a Personal API token, the user must be a member of the specified stack.
If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.

header

true

integer

id ID of the schedule. path true integer

`204` response

OK.

`401` response

`403` response

`404` response

`409` response

Cannot re-activate an expired schedule.

Content types: `application/json`

ErrorResponseApiModel properties:

Name	Description	Required	Type
`error`		`true`	`ErrorApiModel`

Details of the error.

ErrorApiModel properties:

Name	Description	Required	Type
`code`	Service-defined error code.	`true`	`string`
`details`	Array of objects with more specific error information when applicable.	`false`	`array` \| `null`
`message`	Human-readable string describing the error.	`true`	`string`
`target`	A string indicating the target of the error. For example, the name of the property in error.	`false`	`string` \| `null`

`500` response

Deactivate a schedule

POST /cloud/v6/schedules/{id}/deactivate

Deactivate a schedule.

A deactivated schedule will not trigger new test runs. Disabling a schedule does not affect the schedule recurrence rule and does not delay its expiration.

The operation has no effect if the schedule is expired.

Request parameters

Name Description In Required Type

X-Stack-Id

Numeric ID of the Grafana stack representing the request scope.

If the API is called with a Personal API token, the user must be a member of the specified stack.
If the API is called with a Grafana Stack API token, the value must be the ID of the corresponding stack.

header

true

integer

id ID of the schedule. path true integer

`204` response

OK.

`401` response

`403` response

`404` response

`500` response

Was this page helpful?

Email docs@grafana.com

Help and support

Community

Schedules REST API

Get the load test schedule

Request parameters

200 response

Content types: application/json

Deactivated example

EveryTwoHours example

TriggeredOnceInThePast example

WeeklyOnWeekendsStopsAfter10Runs example

401 response

403 response

404 response

500 response

Set a schedule for the load test

Request parameters

Request body

Content types: application/json

EveryTwoHours example

TriggeredOnce example

WeeklyOnWeekendsStopsAfter10Runs example

200 response

Content types: application/json

Deactivated example

EveryTwoHours example

TriggeredOnceInThePast example

WeeklyOnWeekendsStopsAfter10Runs example

400 response

401 response

403 response

404 response

500 response

List all schedules

Request parameters

200 response

Content types: application/json

OK example

400 response

401 response

403 response

500 response

Get a schedule by ID

Request parameters

200 response

Content types: application/json

Deactivated example

EveryTwoHours example

TriggeredOnceInThePast example

WeeklyOnWeekendsStopsAfter10Runs example

401 response

403 response

404 response

500 response

Delete a schedule

Request parameters

204 response

401 response

403 response

404 response

500 response

Re-activate deactivated schedule

Request parameters

204 response

401 response

403 response

404 response

409 response

Content types: application/json

500 response

Deactivate a schedule

Request parameters

204 response

401 response

403 response

404 response

500 response

Was this page helpful?

Related resources from Grafana Labs

`200` response

Content types: `application/json`

`401` response

`403` response

`404` response

`500` response

Content types: `application/json`

`200` response

Content types: `application/json`

`400` response

`401` response

`403` response

`404` response

`500` response

`200` response

Content types: `application/json`

`400` response

`401` response

`403` response

`500` response

`200` response

Content types: `application/json`

`401` response

`403` response

`404` response

`500` response

`204` response

`401` response

`403` response

`404` response

`500` response

`204` response

`401` response

`403` response

`404` response

`409` response

Content types: `application/json`

`500` response

`204` response

`401` response

`403` response

`404` response

`500` response