> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples.md).

# API Examples

Welcome to the API examples section. Here, you’ll find practical demonstrations of how to interact with our API endpoints using cURL commands. Examples include authentication, request parameters, resp

### Structure of the Examples

* cURL-based examples: Every example shows the exact cURL command you can copy and run directly in your terminal.
* Endpoint-specific demonstrations: We walk through different API endpoints one by one, highlighting the required parameters and common use cases.
* Request & Response clarity: Each section contains both the request (what you send) and the response (what you get back) to illustrate expected behavior.

The examples cover two families of endpoints:

* **Data query APIs**: search and aggregate observability data (logs, traces, Kubernetes events, metrics). Logs, traces, and events are queried with [gcQL](https://docs.groundcover.com/investigate/querying-your-groundcover-data/groundcover-query-language.md) through the [Query Data with gcQL](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-data-gcql.md) endpoints; metrics are queried with [MetricsQL](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-metrics.md).
* **Management APIs**: manage platform resources such as dashboards, monitors, notification routes, destinations, synthetics, access policies, and pipelines.

### Base URL

The canonical base URL for the groundcover API is `https://api.groundcover.com`. Some examples show `https://app.groundcover.com`, which serves the same API.

{% hint style="info" %}
Self-hosted ([onPrem](https://docs.groundcover.com/architecture/overview.md#onprem) / [airGapped](https://docs.groundcover.com/architecture/overview.md#airgapped)) deployments use their own API URL. Replace `https://api.groundcover.com` with your environment's endpoint everywhere in these examples, and use an API key generated in that environment's console - API keys are only valid for the environment that issued them.
{% endhint %}

### Prerequisites

Before running any of the examples, make sure you have:

1. [API Key](https://docs.groundcover.com/administer/api-keys.md)
2. Backend ID

The Backend ID can be obtained from your groundcover Admin panel.

**To locate it:**

* Navigate to Settings → Access
* Open the API Keys tab
* The Backend ID appears in the section header

**When to Use**

Include `X-Backend-Id` in the examples to route requests to the intended backend. It is required for multi-backend accounts and for operations whose handlers require backend context. Individual pages describe additional role and deployment requirements.

```yaml
X-Backend-Id: <YOUR_BACKEND_ID>
```

### Permissions

An API key uses the permissions of its [service account](https://docs.groundcover.com/administer/service-accounts.md). **Admin required** means that identity must have Admin (`admin`) permission through its [RBAC policies](https://docs.groundcover.com/administer/role-based-access-control-rbac.md). Editor (`write`) and Viewer (`read`) permissions do not satisfy an Admin-only operation; an insufficient role returns `403 Forbidden`. The role of the person who created the key does not grant extra permissions to the key.

Each API page describes the permissions required for its operations and any additional authenticated-user requirements.

### API guides

For typed clients and installation instructions, see [API SDKs](https://docs.groundcover.com/reference/remote-access-and-apis/sdks.md). Some Agent operations require an authenticated user rather than a service-account API key; their pages identify this requirement.

#### Data queries

* [Query Data with gcQL](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-data-gcql.md)
* [Search Responses and Streaming](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/search-v3-and-streaming.md)
* [Query gcQL Time Series](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/time-series-queries.md)
* [Query Metrics](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-metrics.md)
* [Query APM Measurements](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-apm-measurements.md)
* [Query Database Measurements](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-database-measurements.md)
* [Query Ingestion Measurements](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-ingestion-measurements.md)
* [Query RUM and Upload Source Maps](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-rum.md)
* [Query AI Observability](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-ai-observability.md)
* [Query AWS Cloud Costs](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-cloud-costs.md)
* [Query Infrastructure Entities](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-entities.md)
* [Query Profiling Flamegraphs](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/query-profiling.md)
* [Discover Fields and Metrics](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/discover-fields-and-metrics.md)

#### Dashboards and saved views

* [Dashboards API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/dashboards-api.md)
* [Saved Views API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/saved-views-api.md)
* [Export Dashboards and Issue Graphs](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/export-dashboards-and-issues.md)

#### Monitors and notifications

* [Monitors v2 API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/monitors-v2-api.md)
* [Legacy Monitor Read Compatibility](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/legacy-monitor-reads.md) — list and read definitions on backends without v2.
* [Monitor Issues API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/monitor-issues-api.md)
* [Notification Routes API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/notification-routes-api.md)
* [Destinations API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/destinations-api.md)
* [Silences API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/silences-api.md)
* [Recurring Silences API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/recurring-silences-api.md)

#### Collection and storage

* [Log Pipelines API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/log-pipelines-api.md)
* [Trace Pipelines API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/trace-pipelines-api.md)
* [Metric Pipelines API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/metric-pipelines-api.md)
* [Metrics Aggregation API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/metrics-aggregation-api.md)
* [Data Integrations API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/data-integrations-api.md)
* [Synthetics API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/synthetics-api.md)
* [Storage Management API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/storage-management-api.md)

#### Access and administration

* [Service Accounts API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/service-accounts-api.md)
* [API Keys API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/api-keys-api.md)
* [RBAC Policies API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/rbac-policies-api.md)
* [Secrets API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/secrets-api.md)
* [Member Management API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/members-api.md)
* [Workspace Settings API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/tenant-settings-api.md)

#### Agent Mode

* [Agent API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/agent-api.md)
* [Agent Skills API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/agent-skills-api.md)

Existing infrastructure listing, ingestion-key, and individual monitor examples remain available in the navigation. Workflow examples describe legacy endpoints; use Destinations and Notification Routes for new notification automation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.groundcover.com/reference/remote-access-and-apis/api-examples.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
