Documentation

Grafana Cloud

Testing and synthetics

Performance testing

Reference pages

Cloud REST API

Projects

Grafana Cloud

Projects REST API

List all projects

GET /cloud/v6/projects

List all available projects.

Request parameters

Name	Description	In	Required	Type
`stackId`	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`
`$orderby`	Comma-separated list of fields to use when ordering the results. Available fields: created The default ascending order can be reversed by appending the `desc` specifier.	`query`	`false`	`string`
`$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 type: `application/json`

ProjectListResponse 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[ProjectApiModel]`

ProjectApiModel properties:

Name	Description	Required	Type
`created`	The date when the project was created.	`true`	`string` , format: `date-time`
`id`	Project ID.	`true`	`integer`
`is_default`	Use this project as default for running tests when no explicit project ID is provided.	`true`	`boolean`
`name`	Project name.	`true`	`string`
`updated`	The date when the project was last updated.	`true`	`string` , format: `date-time`

OK example

{
  "@count": 123,
  "@nextLink": "https://api.k6.io/cloud/v6/projects?$skip=50\u0026$top=20",
  "value": [
    {
      "created": "2024-12-04T19:57:46.339Z",
      "id": 123,
      "is_default": false,
      "name": "My Project",
      "updated": "2024-12-04T19:57:46.339Z"
    }
  ]
}

`400` response

`401` response

`403` response

`500` response

Create a project

POST /cloud/v6/projects

Create a new project.

Request parameters

Name Description In Required Type

stackId

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

Request body

Content type: `application/json`

CreateProjectApiModel properties:

Name	Description	Required	Type
`name`	Project name.	`true`	`string`

Create example

{
  "name": "My Project"
}

`201` response

OK.

Content type: `application/json`

ProjectApiModel properties:

Name	Description	Required	Type
`created`	The date when the project was created.	`true`	`string` , format: `date-time`
`id`	Project ID.	`true`	`integer`
`is_default`	Use this project as default for running tests when no explicit project ID is provided.	`true`	`boolean`
`name`	Project name.	`true`	`string`
`updated`	The date when the project was last updated.	`true`	`string` , format: `date-time`

OK example

{
  "created": "2024-12-04T19:57:46.339Z",
  "id": 123,
  "is_default": false,
  "name": "My Project",
  "updated": "2024-12-04T19:57:46.339Z"
}

`400` response

`401` response

`403` response

`500` response

Delete a project

DELETE /cloud/v6/projects/{id}

Delete a project.

Request parameters

Name Description In Required Type

stackId

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 project. path true integer

`204` response

OK.

`401` response

`403` response

`404` response

`409` response

Cannot delete project with a running test.

Content type: `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

Get a project by ID

GET /cloud/v6/projects/{id}

Retrieve a single project.

Request parameters

Name Description In Required Type

stackId

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 project. path true integer

`200` response

OK.

Content type: `application/json`

ProjectApiModel properties:

Name	Description	Required	Type
`created`	The date when the project was created.	`true`	`string` , format: `date-time`
`id`	Project ID.	`true`	`integer`
`is_default`	Use this project as default for running tests when no explicit project ID is provided.	`true`	`boolean`
`name`	Project name.	`true`	`string`
`updated`	The date when the project was last updated.	`true`	`string` , format: `date-time`

OK example

{
  "created": "2024-12-04T19:57:46.339Z",
  "id": 123,
  "is_default": false,
  "name": "My Project",
  "updated": "2024-12-04T19:57:46.339Z"
}

`401` response

`403` response

`404` response

`500` response

Update a project

PATCH /cloud/v6/projects/{id}

Update a project.

Request parameters

Name Description In Required Type

stackId

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 project. path true integer

Request body

Content type: `application/json`

PatchProjectApiModel properties:

Name	Description	Required	Type
`name`	Project name.	`true`	`string`

Update example

{
  "name": "New Project Name"
}

`204` response

OK.

`400` response

`401` response

`403` response

`404` response

`500` response

Get project limits

GET /cloud/v6/projects/{id}/limits

Fetch limits for a project.

Request parameters

Name Description In Required Type

stackId

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 project. path true integer

`200` response

OK.

Content type: `application/json`

ProjectLimitsApiModel properties:

Name	Description	Required	Type
`duration_max_per_test`	Max duration of a test in seconds.	`true`	`integer` \| `null`
`project_id`	ID of the related project.	`true`	`integer`
`vu_browser_max_per_test`	Max number of concurrent browser virtual users (VUs) used in one test.	`true`	`integer` \| `null`
`vu_max_per_test`	Max number of concurrent virtual users (VUs) used in one test.	`true`	`integer` \| `null`
`vuh_max_per_month`	Max amount of virtual user hours (VUH) used per one calendar month.	`true`	`integer` \| `null`

OK example

{
  "duration_max_per_test": 600,
  "project_id": 123,
  "vu_browser_max_per_test": 5,
  "vu_max_per_test": null,
  "vuh_max_per_month": 50
}

`401` response

`403` response

`404` response

`500` response

Update project limits

PATCH /cloud/v6/projects/{id}/limits

Update limits for a project.

Set a limit to null to remove it.

Request parameters

Name Description In Required Type

stackId

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 project. path true integer

Request body

Content type: `application/json`

PatchProjectLimitsRequest properties:

Name	Description	Required	Type
`duration_max_per_test`	Max duration of a test in seconds.	`false`	`integer` \| `null`
`vu_browser_max_per_test`	Max number of concurrent browser virtual users (VUs) used in one test.	`false`	`integer` \| `null`
`vu_max_per_test`	Max number of concurrent virtual users (VUs) used in one test.	`false`	`integer` \| `null`
`vuh_max_per_month`	Max amount of virtual user hours (VUH) used per one calendar month.	`false`	`integer` \| `null`

RemoveAll example

{
  "duration_max_per_test": null,
  "vu_browser_max_per_test": null,
  "vu_max_per_test": null,
  "vuh_max_per_month": null
}

RemoveSingle example

{
  "duration_max_per_test": null
}

UpdateAll example

{
  "duration_max_per_test": 600,
  "vu_browser_max_per_test": 5,
  "vu_max_per_test": 20,
  "vuh_max_per_month": 50
}

UpdateSingle example

{
  "vuh_max_per_month": 55
}

`204` response

OK.

`400` response

`401` response

`403` response

`404` response

`500` response

Was this page helpful?

Email docs@grafana.com

Help and support

Community

Projects REST API

List all projects

Request parameters

200 response

Content type: application/json

OK example

400 response

401 response

403 response

500 response

Create a project

Request parameters

Request body

Content type: application/json

Create example

201 response

Content type: application/json

OK example

400 response

401 response

403 response

500 response

Delete a project

Request parameters

204 response

401 response

403 response

404 response

409 response

Content type: application/json

500 response

Get a project by ID

Request parameters

200 response

Content type: application/json

OK example

401 response

403 response

404 response

500 response

Update a project

Request parameters

Request body

Content type: application/json

Update example

204 response

400 response

401 response

403 response

404 response

500 response

Get project limits

Request parameters

200 response

Content type: application/json

OK example

401 response

403 response

404 response

500 response

Update project limits

Request parameters

Request body

Content type: application/json

RemoveAll example

RemoveSingle example

UpdateAll example

UpdateSingle example

204 response

400 response

401 response

403 response

404 response

500 response

Was this page helpful?

Related documentation

Related resources from Grafana Labs

`200` response

Content type: `application/json`

`400` response

`401` response

`403` response

`500` response

Content type: `application/json`

`201` response

Content type: `application/json`

`400` response

`401` response

`403` response

`500` response

`204` response

`401` response

`403` response

`404` response

`409` response

Content type: `application/json`

`500` response

`200` response

Content type: `application/json`

`401` response

`403` response

`404` response

`500` response

Content type: `application/json`

`204` response

`400` response

`401` response

`403` response

`404` response

`500` response

`200` response

Content type: `application/json`

`401` response

`403` response

`404` response

`500` response

Content type: `application/json`

`204` response

`400` response

`401` response

`403` response

`404` response

`500` response