--- title: "The Tenant HTTP API | Grafana Cloud documentation" description: "Reference documentation for the Grafana Fleet Management Tenant HTTP API whose GetLimits endpoint allows users to retrieve collector, pipeline, and RPS limits for their stack." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # The Tenant HTTP API The Grafana Fleet Management Tenant API allows you to retrieve information about your stack. Calls to the API can give you aggregated analytics about your fleet’s composition and health status. They can also tell you what limits, if any, apply to your stack, and read or replace the stack’s settings document. The data returned by the `GetSummary` endpoint powers the **Overview** tab in the Fleet Management application. ## Find the base URL You can find the base URL for the Tenant API in the Grafana Cloud Fleet Management interface. 1. In your Grafana Cloud stack, click **Connections** > **Fleet Management** in the left-side menu. 2. On the Fleet Management interface, switch to the **API** tab. 3. Find the URL in the **Base URL** section. It looks like one of the following URLs, depending on the region where your Grafana Cloud stack is hosted. Flat format, where `` is the production cluster of your stack: ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```none https://fleet-management-.grafana.net/tenant.v1.TenantService/ ``` Nested format, where `` is the cloud provider, `` is the cloud provider’s region identifier, and `` distinguishes multiple Grafana Cloud regions hosted in the same cloud provider region: ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```none https://fleet-management-.--.grafana.net/tenant.v1.TenantService/ ``` > Caution > > Always copy the exact URL from your Fleet Management interface instead of constructing it by hand. For details on the URL differences, refer to [Determine Grafana Cloud URLs based on region](https://grafana.com/docs/grafana-cloud/security-and-account-management/region-url-formats/). ### Secure connection If you need to secure your API traffic, you can configure a private endpoint in place of the base URL. You can find the service name for endpoint configuration and the private DNS name on the same **API** tab where the base URL is found. For more information, refer to the instructions for your cloud provider: - [AWS PrivateLink](https://grafana.com/docs/grafana-cloud/send-data/fleet-management/set-up/connectivity-options/aws-privatelink/) - [Azure Private Link](https://grafana.com/docs/grafana-cloud/send-data/fleet-management/set-up/connectivity-options/azure-private-link/) - [GCP Private Service Connect](https://grafana.com/docs/grafana-cloud/send-data/fleet-management/set-up/connectivity-options/gcp-private-service-connect/) ## TenantService `TenantService` is the service that provides information about the tenant. Expand table | Method Name | Request Type | Response Type | Description | |----------------------|-----------------------------|------------------------------|-------------------------------------------------------------------------------------------------------------------------| | GetLimits | GetLimitsRequest | GetLimitsResponse | Returns the limits applied to the stack | | GetSummary | GetSummaryRequest | GetSummaryResponse | Returns aggregated analytics of the stack | | GetTenantSettings | GetTenantSettingsRequest | GetTenantSettingsResponse | Returns the stack’s settings. No stored row returns an empty document, and each unset field uses that feature’s default | | UpdateTenantSettings | UpdateTenantSettingsRequest | UpdateTenantSettingsResponse | Writes the masked fields when `expected_revision` matches. The row stays in place | ## Endpoints > Note > > Protobuf field names are defined in `snake_case`. Due to default protojson behavior, field names are converted to `camelCase` in responses. Both `snake_case` and `camelCase` field names are accepted in requests. ### GetLimitsRequest `GetLimitsRequest` is a request to retrieve the collector, pipeline, and requests per second (RPS) limits for a stack. ### GetLimitsResponse `GetLimitsResponse` is the response to a `GetLimitsRequest`. It contains all limits applied to the stack. If a limit field is omitted in the response, that limit does not apply to the stack. For example, if the response does not contain the `collectors` field, the stack does not have a limit on the number of collectors. Expand table | Field | Type | Label | Description | |-----------------------|---------------|-------|-------------------------------------------------------------------| | collectors | integer | | The limit on the number of collectors for the tenant | | pipelines | integer | | The limit on the number of configuration pipelines for the tenant | | requests\_per\_second | RequestLimits | | The request limits for the tenant | ### RequestLimits Expand table | Field | Type | Label | Description | |-----------|---------|-------|-------------------------------------------------------------------| | collector | integer | | The limit on the number of requests per second for collectors | | api | integer | | The limit on the number of requests per second for the API and UI | ### GetSummaryRequest The GetSummaryRequest is a request to retrieve collector and pipeline analytics for the stack. ### GetSummaryResponse The GetSummaryResponse contains summarized analytics for collectors and pipelines, as well as the health status of your fleet. Expand table | Field | Type | Label | Description | |------------|------------------|-------|---------------------------------------------------------------------| | collectors | CollectorSummary | | Summary analytics about all collectors in the stack | | pipelines | PipelineSummary | | Summary analytics about all configuration pipelines in the stack | | limits | LimitsSummary | | Summary analytics about collector and pipeline limits for the stack | ### CollectorSummary CollectorSummary aggregates collectors by several characteristics. If no collectors are registered, the response returns an empty `collectors` object and all other fields are omitted. For all other fields, the field is omitted from the response if no collectors match. Expand table | Field | Type | Label | Description | |----------------|------------------|----------|--------------------------------------------------------------------------------------------| | total | integer | required | Total number of collectors in the stack | | health\_status | map(string, int) | required | Number of collectors by health status: healthy, warning, error, offline, `0` if none apply | | by\_type | map(string, int) | optional | Number of collectors by type: ALLOY or OTEL | | by\_version | map(string, int) | optional | Number of collectors by collector version | | by\_os | map(string, int) | optional | Number of collectors by operating system | ### PipelineSummary PipelineSummary aggregates configuration pipelines in total and by external sync source. If no pipelines exist, the response returns an empty `pipelines` object and all other fields are omitted. Expand table | Field | Type | Label | Description | |------------------|------------------|----------|-----------------------------------------------------------------------------------------| | total | integer | required | Total number of configuration pipelines in the stack | | by\_sync\_source | map(string, int) | optional | Number of configuration pipelines for each source: GIT, TERRAFORM, GRAFANA, UNSPECIFIED | ### LimitsSummary LimitsSummary provides the current total and stack limit for collectors and configuration pipelines. The current count of collectors includes active collectors only. Expand table | Field | Type | Label | Description | |------------|--------|-------|-------------------------------------------------------| | collectors | Limits | | Current total and maximum limit for active collectors | | pipelines | Limits | | Current total and maximum limit for pipelines | #### Limits Expand table | Field | Type | Label | Description | |---------|---------|-------|-----------------------------------------------------------| | current | integer | | The current count of active collectors or total pipelines | | max | integer | | The maximum allowed count, or -1 if unlimited | ### GetTenantSettingsRequest `GetTenantSettingsRequest` retrieves the settings document for the authorized stack. The request body is empty. ### GetTenantSettingsResponse `GetTenantSettingsResponse` contains the settings document and the revision of the stored row. No stored row returns an empty `settings` object and no `revision` field, which clients read as revision 0. An unset field uses that feature’s default. A missing row means every field is unset, so every feature uses its default. `TenantSettings` has no fields yet. Later sections are added to that message. Expand table | Field | Type | Label | Description | |----------|----------------|-------|----------------------------------------------------------------------------| | settings | TenantSettings | | The stack’s settings document. Empty when no settings have been defined | | revision | integer | | The stored revision. 0, and omitted from JSON, when nothing has been saved | ### UpdateTenantSettingsRequest `UpdateTenantSettingsRequest` writes the settings document for the authorized stack. Send the `revision` from the last get as `expected_revision`. The first write uses `0`. A mismatched revision is rejected and the stored document is left unchanged. `update_mask` lists the fields to change. An empty mask writes `settings` as given. A path the server does not know is rejected. A listed field that is unset on the request clears that stored field. A value is stored even when it equals the feature default. The first write that sets a field creates the row. Later writes update it in place. Expand table | Field | Type | Label | Description | |--------------------|----------------|-------|--------------------------------------------------------------------------| | settings | TenantSettings | | The settings values to write | | update\_mask | FieldMask | | Paths to copy onto the stored document. Empty writes `settings` as given | | expected\_revision | integer | | Revision from the last get. `0` when nothing is stored | ### UpdateTenantSettingsResponse `UpdateTenantSettingsResponse` returns the document that was stored and its new revision. Expand table | Field | Type | Label | Description | |----------|----------------|-------|---------------------------------------| | settings | TenantSettings | | The settings document after the write | | revision | integer | | The revision stored by this write | ## Examples The following request retrieves limits for the authorized stack. The Basic Auth username and password are set as environment variables. shell ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl -s \ -u "$GCLOUD_INSTANCE_ID:$GCLOUD_FM_API_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{}' \ https://fleet-management-prod-001.grafana.net/tenant.v1.TenantService/GetLimits \ | jq ``` This is the response showing all limits: JSON ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```json { "pipelines": 200, "collectors": 2000, "requestsPerSecond": { "collector": 20, "api": 3 } } ``` The following request retrieves aggregated analytics for collectors and pipelines in the authorized stack. The Basic Auth username and password are set as environment variables. shell ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```shell curl -s \ -u "$GCLOUD_INSTANCE_ID:$GCLOUD_FM_API_TOKEN" \ -H "Content-Type: application/json" \ -X POST \ -d '{}' \ https://fleet-management-prod-001.grafana.net/tenant.v1.TenantService/GetSummary \ | jq ``` This is the response showing collector and pipeline analytics: JSON ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```json { "collectors": { "total": 2000, "healthStatus": { "healthy": 1800, "warning": 100, "error": 50, "offline": 50 }, "byType": { "ALLOY": 1900, "OTEL": 100 }, "byVersion": { "v0.142.0": 100, "v1.11.3": 1200, "v1.12.0": 700 }, "byOs": { "linux": 1500, "darwin": 300, "windows": 200 } }, "pipelines": { "total": 180, "bySyncSource": { "GIT": 130, "TERRAFORM": 20 "UNSPECIFIED": 30 } }, "limits": { "collectors": { "current": 1950, "max": 2000 }, "pipelines": { "current": 180, "max": 200 } } } ```