Grafana Cloud

https://grafana.com/docs/grafana-cloud/
Admin
Grafana Cloud is an AI-powered observability platform that enables monitoring, analysis, and faster...
Tokens:5,356,716
Snippets:37,293
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### List quickstarts - JSON response

Source: https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/quickstarts

Example response for the GET /quickstarts endpoint. Shows a successful response with a quickstart object and pagination details.

```json
{
  "status": "success",
  "data": {
    "quickstarts": [
      {
        "id": "c5d3e4f6-7890-1234-cdef-056789012345",
        "created": "2025-11-15T10:00:00Z",
        "modified": "2025-11-15T10:00:00Z",
        "createdBy": "sa-5594@serviceaccount.grafana",
        "updatedBy": "sa-5594@serviceaccount.grafana",
        "title": "SLO health",
        "prompt": "How healthy are my SLOs right now?",
        "enabled": true,
        "scope": "tenant"
      }
    ],
    "pagination": {
      "total": 1,
      "limit": 20,
      "offset": 0
    }
  }
}
```

--------------------------------

### Get quickstart curl example

Source: https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/quickstarts

Bash command to retrieve a quickstart by ID using the GET /quickstarts/{id} endpoint. Requires ASSISTANT_API_URL and SERVICE_ACCOUNT_TOKEN environment variables.

```bash
QUICKSTART_ID="c5d3e4f6-7890-1234-cdef-056789012345"

curl -X GET "${ASSISTANT_API_URL}/quickstarts/${QUICKSTART_ID}" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}"
```

--------------------------------

### Update quickstart response example

Source: https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/quickstarts

Example JSON response for a successful PUT /quickstarts/{id} request. Shows the full updated quickstart object, including the modified timestamp and updated fields.

```json
{
  "status": "success",
  "data": {
    "id": "c5d3e4f6-7890-1234-cdef-056789012345",
    "created": "2025-11-15T10:00:00Z",
    "modified": "2025-11-20T14:15:00Z",
    "createdBy": "sa-5594@serviceaccount.grafana",
    "updatedBy": "sa-5594@serviceaccount.grafana",
    "title": "SLO health",
    "prompt": "How healthy are my SLOs right now?",
    "enabled": false,
    "scope": "tenant"
  }
}
```

--------------------------------

### List quickstarts - curl example

Source: https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/quickstarts

Bash command to list quickstarts with scope=tenant and enabled_only=true. Uses the ASSISTANT_API_URL and SERVICE_ACCOUNT_TOKEN environment variables.

```bash
curl -X GET "${ASSISTANT_API_URL}/quickstarts?scope=tenant&enabled_only=true" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}"
```

--------------------------------

### Create quickstart with curl

Source: https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/quickstarts

Bash example using `curl` to create a quickstart. Requires the base URL and service account token described in the Grafana Assistant HTTP API reference.

```bash
curl -X POST "${ASSISTANT_API_URL}/quickstarts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" \
  -d '{
    "scope": "tenant",
    "title": "SLO health",
    "prompt": "How healthy are my SLOs right now?",
    "enabled": true
  }'
```

--------------------------------

### Get HTTP requests in time range with query_aggregate_k6

Source: https://grafana.com/docs/grafana-cloud/observe-and-act/testing/k6/reference/cloud-rest-api/metrics

Cheat sheet example to get the number of HTTP requests made within a specific time period, using start and end timestamps.

```none
/cloud/v5/test_runs/:testRunId/query_aggregate_k6(metric='http_reqs',query='increase',start=2021-08-09T12:01:10Z,end=2021-08-09T12:09:13Z)
```

--------------------------------

### Create quickstart response

Source: https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/quickstarts

Example response from the `POST /quickstarts` endpoint. Shows the created quickstart object with its `id`, timestamps, and the service account that created and updated it.

```json
{
  "status": "success",
  "data": {
    "id": "c5d3e4f6-7890-1234-cdef-056789012345",
    "created": "2025-11-15T10:00:00Z",
    "modified": "2025-11-15T10:00:00Z",
    "createdBy": "sa-5594@serviceaccount.grafana",
    "updatedBy": "sa-5594@serviceaccount.grafana",
    "title": "SLO health",
    "prompt": "How healthy are my SLOs right now?",
    "enabled": true,
    "scope": "tenant"
  }
}
```

--------------------------------

### Verify pg_stat_statements extension

Source: https://grafana.com/docs/grafana-cloud/monitor-applications/database-observability/troubleshoot/postgres

Run this query in each monitored database to confirm the pg_stat_statements extension is installed. If the query returns no rows, the extension is missing and must be enabled as described in the setup guide.

```sql
SELECT * FROM pg_extension WHERE extname = 'pg_stat_statements';
```

--------------------------------

### GET /cloud/v5/test_runs/:testRunId/query_aggregate_k6(:parameters)

Source: https://grafana.com/docs/grafana-cloud/observe-and-act/testing/k6/reference/cloud-rest-api/metrics

This snippet documents the GET /cloud/v5/test_runs/:testRunId/query_aggregate_k6(:parameters) endpoint, including its parameters, request example, response example, and cheat sheet examples.

```APIDOC
## GET /cloud/v5/test_runs/:testRunId/query_aggregate_k6(:parameters)

### Description
Aggregate query returns a single sample value for a given metric over the duration of the test run. Parameters are a comma-separated list in the format of `key=value`. String values should be surrounded by single quotes `'`.

### Method
GET

### Endpoint
`/cloud/v5/test_runs/:testRunId/query_aggregate_k6(:parameters)`

### Parameters
#### Path Parameters
- **testRunId** (string) - Required - The ID of the test run.

#### Query Parameters
- **query** (string) - Required - Query expression for selecting metrics. Possible values depend on the metric type.
- **metric** (string) - Required - Name of the metric to query, with optional labels selector. Example: `http_reqs{expected_response="true"}`
- **start** (iso8601) - Optional - The start timestamp for the query range. Default is test run start. Example: `2022-01-02T10:03:00Z`
- **end** (iso8601) - Optional - The end timestamp for the query range. Default is test run end. Example: `2022-01-02T10:13:00Z`

### Request Example
```http
GET https://api.k6.io/cloud/v5/test_runs/152779/query_aggregate_k6(query='histogram_quantile(0.95) by (name,status)',metric='http_req_duration')
Accept: application/json
Authorization: Bearer 56c166885f9a7fc1e588a1b3cb66f6dd
```

### Response
#### Success Response (200)
- **status** (string) - Status of the response, e.g., "success".
- **data** (object) - Contains the result data.
  - **resultType** (string) - Type of the result, e.g., "vector".
  - **result** (array) - Array of result objects.
    - **metric** (object) - Metric labels.
    - **values** (array) - Array of [timestamp, value] pairs.

#### Response Example
```http
HTTP/1.1 200
Content-Type: application/json

{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {
          "__name__": "http_req_duration",
          "name": "http://test.k6.io/?q=2",
          "status": "200",
          "test_run_id": "152779"
        },
        "values": [
          [
            1684950639,
            14207
          ]
        ]
      },
      {
        "metric": {
          "__name__": "http_req_duration",
          "name": "http://test.k6.io/?q=1",
          "status": "500",
          "test_run_id": "152779"
        },
        "values": [
          [
            1684950639,
            28031
          ]
        ]
      }
    ]
  }
}
```

### Cheat Sheet Examples
- Get the total number of HTTP requests made during the test run:
  `/cloud/v5/test_runs/:testRunId/query_aggregate_k6(metric='http_reqs',query='increase')`
- Get the number of HTTP requests made within a specific time period:
  `/cloud/v5/test_runs/:testRunId/query_aggregate_k6(metric='http_reqs',query='increase',start=2021-08-09T12:01:10Z,end=2021-08-09T12:09:13Z)`
- Get the 95th percentile of HTTP request response times, separated by URL, HTTP method, and HTTP status code:
  `/cloud/v5/test_runs/:testRunId/query_aggregate_k6(metric='http_req_duration',query='historgam_quantile(0.95) by (name,method,status)')`
- Get the peak requests per second during the test run with 5 second precision, for requests with statuses 2xx and 3xx, separated by URL:
  `/cloud/v5/test_runs/:testRunId/query_aggregate_k6(metric='http_reqs{status~="[23][0-9]{2}"}',query='max_rate(5) by (name)')`
- Get peak CPU usage of each instance during test run, averaged between instances:
  `/cloud/v5/test_runs/:testRunId/query_aggregate_k6(metric='load_generator_cpu_percent',query='avg(max by (instance))')`
- Get peak simultaneous VUs during the test run:
  `/cloud/v5/test_runs/:testRunId/query_aggregate_k6(metric='vus',query='sum(max by (instance_id))')`
```

--------------------------------

### Create tutorial directory and docker-compose.yml

Source: https://grafana.com/docs/grafana-cloud/send-data/alloy/tutorials/send-logs-to-loki

Creates a directory for the tutorial and an empty docker-compose.yml file.

```bash
mkdir alloy-tutorial
cd alloy-tutorial
touch docker-compose.yml
```

--------------------------------

### Example output of mimirtool alertmanager get

Source: https://grafana.com/docs/grafana-cloud/alerting-and-irm/alerting/set-up/configure-alertmanager/add-alertmanager-using-mimirtool

Example output from the 'mimirtool alertmanager get' command, showing the uploaded Alertmanager configuration.

```bash
global:
  smtp_smarthost: 'localhost:25'
  smtp_from: 'youraddress@example.org'
route:
  receiver: example-email
receivers:
 - name: example-email
   email_configs:
    - to: 'youraddress@example.org'

```

--------------------------------

### Example output of binary provisioning

Source: https://grafana.com/docs/grafana-cloud/observe-and-act/testing/k6/author-run/use-k6-extensions

Example output showing that k6 has provisioned a binary with the required k6 and extension versions.

```text
INFO[0287] A new k6 binary has been provisioned with version(s): k6:v1.1.0 k6/x/faker:v0.4.4
```

--------------------------------

### Example GET request to metrics summary API

Source: https://grafana.com/docs/grafana-cloud/send-data/traces/configure/metrics-summary-api

Example GET request to the metrics summary API using a specific Tempo URL.

```none
GET https://tempo-dedicated-02-prod-us-central-0.grafana.net/tempo/api/metrics/summary
```

--------------------------------

### Get a Playlist - Example Response

Source: https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/playlist

Example response for a successful GET request. Returns the playlist object with metadata and spec, including the interval and items.

```http
HTTP/1.1 200
Content-Type: application/json

{
  "kind": "Playlist",
  "apiVersion": "playlist.grafana.app/v1",
  "metadata": {
    "name": "my-playlist-uid",
    "namespace": "default",
    "resourceVersion": "1234567890",
    "creationTimestamp": "2024-01-15T10:30:00Z"
  },
  "spec": {
    "title": "My Playlist",
    "interval": "5m",
    "items": [
      {
        "type": "dashboard_by_uid",
        "value": "dashboard-uid-1"
      },
      {
        "type": "dashboard_by_tag",
        "value": "important"
      }
    ]
  }
}
```

--------------------------------

### GET /api/search/

Source: https://grafana.com/docs/grafana-cloud/learn-and-build/developer-resources/api-reference/http-api/api-legacy/folder_dashboard_search

This snippet documents the GET /api/search/ endpoint for searching folders and dashboards, including query parameters, request examples, and response examples.

```APIDOC
## GET /api/search/

### Description
Searches for folders and dashboards. When using Role-based access control, search results will contain only dashboards and folders which you have access to.

### Method
GET

### Endpoint
/api/search/

### Parameters
#### Query Parameters
- **query** (string) - Optional - Search Query
- **tag** (list of strings) - Optional - List of tags to search for
- **type** (string) - Optional - Type to search for, `dash-folder` or `dash-db`
- **dashboardIds** (list of integers) - Optional - List of dashboard id's to search for
- **dashboardUID** (list of strings) - Optional - List of dashboard uid's to search for. Deprecated since Grafana v9.1, please use dashboardUIDs instead.
- **dashboardUIDs** (list of strings) - Optional - List of dashboard uid's to search for
- **folderUIDs** (list of strings) - Optional - List of folder UIDs to search in
- **starred** (boolean) - Optional - Flag indicating if only starred Dashboards should be returned
- **limit** (integer) - Optional - Limit the number of returned results (max is 5000; default is 1000). If an invalid value is provided (for example, strings or special characters), the parameter defaults to 1000.
- **page** (integer) - Optional - Use this parameter to access hits beyond limit. Numbering starts at 1. limit param acts as page size.

### Request Example
```http
GET /api/search?query=&starred=false HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
```

### Response
#### Success Response (200)
Returns an array of search results. Each result contains fields such as id, uid, orgId, title, url, type, tags, isStarred, and uri (deprecated in Grafana v5.0). For dashboards, additional fields may include folderId, folderUid, folderTitle, and folderUrl.

#### Response Example
```http
HTTP/1.1 200
Content-Type: application/json

[
  {
    "id": 163,
    "uid": "000000163",
    "orgId": 1,
    "title": "Folder",
    "url": "/dashboards/f/000000163/folder",
    "type": "dash-folder",
    "tags": [],
    "isStarred": false,
    "uri":"db/folder" // deprecated in Grafana v5.0
  },
  {
    "id":1,
    "uid": "cIBgcSjkk",
    "orgId": 1,
    "title":"Production Overview",
    "url": "/d/cIBgcSjkk/production-overview",
    "type":"dash-db",
    "tags":[prod],
    "isStarred":true,
    "uri":"db/production-overview" // deprecated in Grafana v5.0
  }
]
```
```

--------------------------------

### GET /quickstarts

Source: https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/quickstarts

Retrieves quickstarts with optional filtering and pagination. Requires appropriate permissions based on the scope.

```APIDOC
## GET /quickstarts

### Description
Retrieve quickstarts with optional filtering and pagination.

### Method
GET

### Endpoint
/quickstarts

### Parameters
#### Query Parameters
- **scope** (string) - Optional - Filter by scope: `user` or `tenant`.
- **enabled_only** (boolean) - Optional - When `true`, return only enabled quickstarts.
- **limit** (integer) - Optional - Maximum number of quickstarts to return. Range: 1-100. Default: `20`.
- **offset** (integer) - Optional - Pagination offset. Default: `0`.

### Request Example
```bash
curl -X GET "${ASSISTANT_API_URL}/quickstarts?scope=tenant&enabled_only=true" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}"
```

### Response
#### Success Response (200)
- **status** (string) - Status of the response, e.g., "success".
- **data.quickstarts** (array) - List of quickstarts.
  - **id** (string) - Unique identifier of the quickstart.
  - **created** (string) - Creation timestamp.
  - **modified** (string) - Last modification timestamp.
  - **createdBy** (string) - Creator service account.
  - **updatedBy** (string) - Last updater service account.
  - **title** (string) - Title of the quickstart.
  - **prompt** (string) - Prompt associated with the quickstart.
  - **enabled** (boolean) - Whether the quickstart is enabled.
  - **scope** (string) - Scope of the quickstart: `user` or `tenant`.
- **data.pagination** (object) - Pagination information.
  - **total** (integer) - Total number of quickstarts.
  - **limit** (integer) - Limit used.
  - **offset** (integer) - Offset used.

#### Response Example
```json
{
  "status": "success",
  "data": {
    "quickstarts": [
      {
        "id": "c5d3e4f6-7890-1234-cdef-056789012345",
        "created": "2025-11-15T10:00:00Z",
        "modified": "2025-11-15T10:00:00Z",
        "createdBy": "sa-5594@serviceaccount.grafana",
        "updatedBy": "sa-5594@serviceaccount.grafana",
        "title": "SLO health",
        "prompt": "How healthy are my SLOs right now?",
        "enabled": true,
        "scope": "tenant"
      }
    ],
    "pagination": {
      "total": 1,
      "limit": 20,
      "offset": 0
    }
  }
}
```

### Permissions
- **user** scope: `grafana-assistant-app.quickstarts.user:read`
- **tenant** scope: `grafana-assistant-app.quickstarts.tenant:read`
```

--------------------------------

### Get a secure value - Example response

Source: https://grafana.com/docs/grafana-cloud/developer-resources/api-reference/http-api/secrets_management

Example response for a successful get request. Returns the secure value metadata and status, but not the secret value itself.

```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 294

{
  "apiVersion": "secret.grafana.app/v1beta1",
  "kind": "SecureValue",
  "metadata": {
    "name": "api-key",
    "namespace": "default",
    "uid": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "creationTimestamp": "2024-01-15T10:35:00Z"
  },
  "spec": {
    "description": "External API Key",
    "decrypters": ["synthetic-monitoring"]
  },
  "status": {}
}
```

--------------------------------

### POST /quickstarts

Source: https://grafana.com/docs/grafana-cloud/platform/grafana-assistant/reference/http-apis/quickstarts

Creates a new quickstart prompt with the specified scope, prompt text, and optional title and enabled flag.

```APIDOC
## POST /quickstarts

### Description
Create a new quickstart prompt.

### Method
POST

### Endpoint
`POST /quickstarts`

### Parameters
#### Request Body
- **scope** (string) - Required - Quickstart scope: `user` or `tenant`.
- **prompt** (string) - Required - The question text shown to users.
- **title** (string) - Optional - A short display title for the quickstart.
- **enabled** (boolean) - Optional - Whether the quickstart is active. Default: `true`.

### Request Example
```json
{
  "scope": "tenant",
  "title": "SLO health",
  "prompt": "How healthy are my SLOs right now?",
  "enabled": true
}
```

### Response
#### Success Response (200)
- **status** (string) - Status of the response.
- **data** (object) - The created quickstart object.
  - **id** (string) - Unique identifier of the quickstart.
  - **created** (string) - Creation timestamp.
  - **modified** (string) - Last modification timestamp.
  - **createdBy** (string) - Identity that created the quickstart.
  - **updatedBy** (string) - Identity that last updated the quickstart.
  - **title** (string) - Display title.
  - **prompt** (string) - The question text.
  - **enabled** (boolean) - Whether the quickstart is active.
  - **scope** (string) - Quickstart scope: `user` or `tenant`.

#### Response Example
```json
{
  "status": "success",
  "data": {
    "id": "c5d3e4f6-7890-1234-cdef-056789012345",
    "created": "2025-11-15T10:00:00Z",
    "modified": "2025-11-15T10:00:00Z",
    "createdBy": "sa-5594@serviceaccount.grafana",
    "updatedBy": "sa-5594@serviceaccount.grafana",
    "title": "SLO health",
    "prompt": "How healthy are my SLOs right now?",
    "enabled": true,
    "scope": "tenant"
  }
}
```

### Permissions
- **user** scope: `grafana-assistant-app.quickstarts.user:create`
- **tenant** scope: `grafana-assistant-app.quickstarts.tenant:create`

### Example
```bash
curl -X POST "${ASSISTANT_API_URL}/quickstarts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${SERVICE_ACCOUNT_TOKEN}" \
  -d '{
    "scope": "tenant",
    "title": "SLO health",
    "prompt": "How healthy are my SLOs right now?",
    "enabled": true
  }'
```
```

--------------------------------

### Create the meta and prod namespaces

Source: https://grafana.com/docs/grafana-cloud/send-data/alloy/monitor/monitor-kubernetes-logs

Creates the `meta` and `prod` Kubernetes namespaces used for the example.

```shell
kubectl create namespace meta && \
kubectl create namespace prod
```

--------------------------------

### Example response for get stack details

Source: https://grafana.com/docs/grafana-cloud/developer-resources/api-reference/cloud-api

Example response for the get stack details request. Shows the full stack object including instance URLs, quotas, and links.

```json
{
  "id": 007303,
  "orgId": 052992,
  "orgSlug": "grafanacom",
  "orgName": "grafanacom",
  "type": "grafana",
  "name": "cloudapistack.grafana.net",
  "url": "https://cloudapistack.grafana.net",
  "slug": "cloudapistack",
  "version": "stable",
  "description": "",
  "status": "active",
  "gateway": "istio",
  "createdAt": "2023-01-04T06:43:24.000Z",
  "createdBy": "foobar",
  "updatedAt": null,
  "updatedBy": "",
  "trial": 0,
  "trialExpiresAt": null,
  "clusterId": 69,
  "clusterSlug": "prod-us-central-0",
  "clusterName": "prod-us-central-0",
  "plan": "gcloud",
  "planName": "Grafana Cloud",
  "billingStartDate": "2023-01-04T06:43:23.000Z",
  "billingEndDate": null,
  "billingActiveUsers": 0,
  "billingGrafanaActiveUsers": 0,
  "billingOnCallActiveUsers": 0,
  "currentActiveUsers": 0,
  "currentActiveAdminUsers": 0,
  "currentActiveEditorUsers": 0,
  "currentActiveViewerUsers": 0,
  "dailyUserCnt": 0,
  "dailyAdminCnt": 0,
  "dailyEditorCnt": 0,
  "dailyViewerCnt": 0,
  "dashboardCnt": 8,
  "datasourceCnts": {},
  "userQuota": 10,
  "dashboardQuota": -1,
  "alertQuota": -1,
  "alertCnt": 0,
  "ssl": true,
  "customAuth": true,
  "customDomain": true,
  "support": true,
  "runningVersion": "9.3.2-45365 (commit: ef5286dd77, branch: v9.3.x)",
  "machineLearning": 0,
  "incident": 0,
  "deleteProtection": false,
  "hmInstancePromId": 715391,
  "hmInstancePromUrl": "https://prometheus-us-central1.grafana.net",
  "hmInstancePromName": "cloudapistack-prom",
  "hmInstancePromStatus": "active",
  "hmInstancePromCurrentUsage": 0,
  "hmInstancePromCurrentActiveSeries": 0,
  "hmInstanceGraphiteId": 715392,
  "hmInstanceGraphiteUrl": "https://graphite-prod-10-prod-us-central-0.grafana.net",
  "hmInstanceGraphiteName": "cloudapistack-graphite",
  "hmInstanceGraphiteType": "graphite-v5",
  "hmInstanceGraphiteStatus": "active",
  "hmInstanceGraphiteCurrentUsage": 0,
  "hlInstanceId": 356665,
  "hlInstanceUrl": "https://logs-prod-017.grafana.net",
  "hlInstanceName": "cloudapistack-logs",
  "hlInstanceStatus": "active",
  "hlInstanceCurrentUsage": 0,
  "amInstanceId": 355647,
  "amInstanceName": "cloudapistack-alerts",
  "amInstanceUrl": "https://alertmanager-us-central1.grafana.net",
  "amInstanceStatus": "active",
  "amInstanceGeneratorUrl": "https://cloudapistack.grafana.net",
  "amInstanceGeneratorUrlDatasource": "",
  "htInstanceId": 353178,
  "htInstanceUrl": "https://tempo-us-central1.grafana.net",
  "htInstanceName": "cloudapistack-traces",
  "htInstanceStatus": "active",
  "regionId": 1,
  "regionSlug": "us",
  "links": [
    {
      "rel": "self",
      "href": "/instances/cloudapistack"
    },
    {
      "rel": "org",
      "href": "/orgs/grafanacom"
    },
    {
      "rel": "plugins",
      "href": "/instances/cloudapistack/plugins"
    }
  ]
}
```
Tokens:
Raw