--- title: "The Collector HTTP API | Grafana Cloud documentation" description: "Reference documentation for the Grafana Fleet Management Collector HTTP API, which offers straightforward CRUD operations on individual collectors as well as bulk deletes and updates." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # The Collector HTTP API The Grafana Fleet Management Collector API offers straightforward CRUD operations on individual collectors as well as bulk deletes and updates. For a full definition of the Collector API, refer to the [`.proto` file](https://github.com/grafana/fleet-management-api/blob/main/api/collector/v1/collector.proto). ## Find the base URL You can find the base URL for the Collector 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](/media/images/icons/icon-copy-small-2.svg) Copy ```none https://fleet-management-.grafana.net/collector.v1.CollectorService/ ``` 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](/media/images/icons/icon-copy-small-2.svg) Copy ```none https://fleet-management-.--.grafana.net/collector.v1.CollectorService/ ``` > 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](/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](/docs/grafana-cloud/send-data/fleet-management/set-up/connectivity-options/aws-privatelink/) - [Azure Private Link](/docs/grafana-cloud/send-data/fleet-management/set-up/connectivity-options/azure-private-link/) - [GCP Private Service Connect](/docs/grafana-cloud/send-data/fleet-management/set-up/connectivity-options/gcp-private-service-connect/) ## Rate limits You can make a request to the [Fleet Management Tenant API](/docs/grafana-cloud/send-data/fleet-management/api-reference/tenant-api/) to find out the requests-per-second limits applied to your stack. Collector API requests are limited based on the endpoint called. - Requests to the `RegisterCollector` and `GetConfig` endpoints are included in the `requests_per_second:collector` limit reported by the Tenant API and limited to 20 requests per second by default. - Requests to the `GetConfig` endpoint that originate in the Fleet Management application (for example, if you view a collector’s remote configuration in the UI) and calls to all other endpoints are included in the `requests_per_second:api` limit reported by the Tenant API. These calls are limited to 3 requests per second by default. ## CollectorService `CollectorService` is the service that is used to register, update, and provide remote configuration for collectors. Expand table | Method Name | Request Type | Response Type | Description | |-------------------------|--------------------------------|---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | GetConfig | GetConfigRequest | GetConfigResponse | Returns the collector’s configuration | | RegisterCollector | RegisterCollectorRequest | RegisterCollectorResponse | Registers the collector with the given ID and attributes and updates the collector’s attributes if the collector is already registered and the attributes are different | | GetCollector | GetCollectorRequest | Collector | Returns information about the collector | | ListCollectors | ListCollectorsRequest | Collectors | Returns information about all collectors | | CreateCollector | CreateCollectorRequest | Collector | Creates a new collector | | UpdateCollector | UpdateCollectorRequest | Collector | Updates an existing collector | | BulkUpdateCollectors | BulkUpdateCollectorsRequest | BulkUpdateCollectorsResponse | Updates multiple collectors | | DeleteCollector | DeleteCollectorRequest | DeleteCollectorResponse | Deletes an existing collector | | BulkDeleteCollectors | BulkDeleteCollectorRequest | BulkDeleteCollectorResponse | Deletes multiple collectors | | ListCollectorAttributes | ListCollectorAttributesRequest | ListCollectorAttributesResponse | Returns all attributes that are used for all collectors | ## 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. ### BulkDeleteCollectorsRequest `BulkDeleteCollectorsRequest` is a request to delete multiple collectors. If any collectors do not exist, the request fails and no collectors are deleted. Expand table | Field | Type | Label | Description | |-------|--------------|----------|-----------------------------| | id | list(string) | required | IDs of collectors to delete | ### BulkDeleteCollectorsResponse `BulkDeleteCollectorsResponse` is the response to a `BulkDeleteCollectorsRequest`. This message is empty and the results of the delete are defined by the HTTP status code of the response. ### BulkUpdateCollectorsRequest `BulkUpdateCollectorsRequest` is a request to update multiple Collectors’ remote attributes in a single request. The update is applied in a single transaction, so any errors cause the entire request to fail and no Collectors are updated. A BulkUpdateCollectorsRequest can be used to add, remove, replace, move, or copy remote attributes for the specified Collectors. Expand table | Field | Type | Label | Description | |-------|-----------------|----------|-----------------------------------------------------------------| | ids | list(string) | required | ID of the Collector to update | | ops | list(Operation) | required | Operations applied to collectors in the order they are provided | ### BulkUpdateCollectorsResponse `BulkUpdateCollectorsResponse` is the response to a `BulkUpdateCollectorsRequest`. This message is empty and the results of the update are defined by the HTTP status code of the response. ### Collector `Collector` represents the data for a single collector. The ID is used to uniquely identify the collector, and the local\_attributes and remote\_attributes are used to determine which pipelines to include in the collector’s configuration. Remote attributes were previously known as attribute overrides. These take precedence over attributes set in the collector’s local configuration except for any attributes prefixed with `collector.`. `collector.*` attributes are reserved for use by the Fleet Management service. Expand table | Field | Type | Label | Description | |----------------------|---------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------| | id | string | required | ID of the collector | | remote\_attributes | map(string) | optional | Attributes stored in Fleet Management | | created\_at | google.protobuf.Timestamp | optional | Timestamp that the collector was created | | updated\_at | google.protobuf.Timestamp | optional | Timestamp that the collector was last updated | | name | string | optional | Name of the collector used for display purposes only | | local\_attributes | map(string) | optional | Last set of attributes received from the collector in a RegisterCollectorRequest | | enabled | bool | optional | Whether remote configuration for the collector is enabled or not | | marked\_inactive\_at | google.protobuf.Timestamp | optional | Timestamp of when the collector was marked inactive | | collector\_type | CollectorType | optional | Type of collector (Grafana Alloy or OpenTelemetry Collector); if unspecified in a `CreateCollector` request, default value is COLLECTOR\_TYPE\_ALLOY | #### CollectorType `CollectorType` represents the type of collector. If the `CollectorType` is left unspecified in a `CreateCollector` request, COLLECTOR\_TYPE\_ALLOY is assigned by default. Expand table | Value | Description | |------------------------------|---------------------------------| | COLLECTOR\_TYPE\_UNSPECIFIED | Collector type is not specified | | COLLECTOR\_TYPE\_ALLOY | Grafana Alloy collector | | COLLECTOR\_TYPE\_OTEL | OpenTelemetry Collector | ### Collectors `Collectors` represents a list of collectors. Expand table | Field | Type | Label | Description | |------------|-----------------|-------|--------------------| | collectors | list(Collector) | | List of collectors | ### CreateCollectorRequest `CreateCollectorRequest` is the request to create a new collector. If no `collector_type` is specified in this request, COLLECTOR\_TYPE\_ALLOY is assigned by default. Expand table | Field | Type | Label | Description | |-----------|-----------|-------|---------------| | collector | Collector | | New collector | ### DeleteCollectorRequest `DeleteCollectorRequest` is the request to delete an existing collector. Expand table | Field | Type | Label | Description | |-------|--------|----------|-------------------------------| | id | string | required | ID of the collector to delete | ### DeleteCollectorResponse `DeleteCollectorResponse` is the response to a `DeleteCollectorRequest`. This message is empty and the results of the delete are defined by the HTTP status code of the response. ### GetCollectorRequest `GetCollectorRequest` is the request to retrieve a collector’s information. Its response is a `Collector` message. Expand table | Field | Type | Label | Description | |-------|--------|----------|---------------------------------| | id | string | required | ID of the collector to retrieve | ### GetConfigRequest `GetConfigRequest` is the request message to get a collector’s configuration. Attributes are key-value pairs. The `local_attributes` supplied in the request are combined with remote attributes stored in Fleet Management to determine which pipelines are included in the collector’s final configuration. Expand table | Field | Type | Label | Description | |------------------------|--------------------|----------|--------------------------------------------------------------------------------------------------------| | id | string | required | ID of the collector the configuration is for | | local\_attributes | map(string) | optional | Local attributes of the collector | | hash | string | optional | Determines if the configuration has changed | | remote\_config\_status | RemoteConfigStatus | optional | Status of the previously received remote config; omit if unchanged since the last GetConfigRequest | | effective\_config | EffectiveConfig | optional | The complete configuration currently in use by the collector; omit if unchanged since the last request | ### GetConfigResponse `GetConfigResponse` is the server-to-collector response message that contains the collector’s configuration. Expand table | Field | Type | Label | Description | |---------------|--------|-------|-------------------------------------------------------------------------------------------------------------| | content | string | | Full configuration for the collector | | hash | string | | Determines if the configuration has changed and avoids sending the full configuration if it has not changed | | not\_modified | bool | | Set to true if the configuration has not changed, indicating the client should not update its configuration | ### RemoteConfigStatus Expand table | Field | Type | Label | Description | |----------------|----------------------|----------|----------------------------------------------------------| | status | RemoteConfigStatuses | | Current status of the last received remote configuration | | error\_message | string | optional | Error message when `status == FAILED` | #### RemoteConfigStatuses Expand table | Value | Description | |----------|-----------------------------------------------------------------------------| | UNSET | Status not set | | APPLIED | Remote config was successfully applied by the collector | | APPLYING | Collector is currently applying the remote config | | FAILED | Applying the previously received remote config failed (see `error_message`) | ### EffectiveConfig Represents the complete configuration that governs the collector’s current behavior, which may differ from the last remote configuration if the collector is using a local configuration instead or in addition. Expand table | Field | Type | Label | Description | |-------------|----------------|-------|---------------------------------| | config\_map | AgentConfigMap | | The effective configuration map | #### AgentConfigMap Expand table | Field | Type | Label | Description | |-------------|-----------------------------------|-------|--------------------------------------------------------------------------------------------------| | config\_map | map(string => AgentConfigFile) | | Map of configs keyed by file/section name; single-file agents may use an empty string as the key | ##### AgentConfigFile Expand table | Field | Type | Label | Description | |---------------|--------|----------|------------------------------------------------------------| | body | bytes | | Config file or section body | | content\_type | string | optional | Optional MIME type describing the body (e.g., `text/yaml`) | ### ListCollectorAttributesRequest `ListCollectorAttributesRequest` is the request to list all attributes that are used for all collectors. ### ListCollectorAttributesResponse `ListCollectorAttributesResponse` is the response to a `ListCollectorAttributesRequest`. It contains maps of all attributes and all their values that are used for all collectors. Expand table | Field | Type | Label | Description | |--------------------|-------------|-------|----------------------------------------------------------| | local\_attributes | map(string) | | Local attributes for all collectors | | remote\_attributes | map(string) | | Attributes stored in Fleet Management for all collectors | The virtual attribute `collector.ID` is returned with an empty value as long as a single collector exists. #### ListCollectorAttributesResponse.AttributesEntry Expand table | Field | Type | |-------|------------| | key | string | | value | Attributes | ##### Attributes Expand table | Field | Type | Label | Description | |--------|-------------|-------|-----------------------------------| | values | list(Value) | | All values for a single attribute | ###### Value Expand table | Field | Type | Label | Description | |-------|--------|-------|-------------------------------| | value | string | | Single value for an attribute | ### ListCollectorsRequest `ListCollectorsRequest` is the request to list collectors according to any specified matchers. If no matchers are specified, all collectors are returned. Expand table | Field | Type | Label | Description | |----------|--------------|-------|---------------------------------------------------------------------------------| | matchers | list(string) | | Matchers used to filter the list of collectors; 200 character limit per matcher | ### Operation `Operation` is a single operation to apply to a collector’s remote attributes. Expand table | Field | Type | Label | Description | |----------|------------------|----------|------------------------------------------------------------------------------------------------| | op | Operation.OpType | required | Operation to perform | | path | string | required | Path for the operation formatted as a JSON path | | from | string | optional | Used by the move and copy operations to specify the source path to move or copy the value from | | value | string | optional | Value for add and replace operations, as well as selective removal | | oldValue | string | optional | Old value to match against for a selective replace | #### Operation.OpType Expand table | Value | Description | |---------|-------------------------------------------------------------------------------------------------------------| | ADD | Adds a new attribute or replaces one with the specified `path` | | REMOVE | Removes the attribute at the specified `path` | | REPLACE | Replaces the existing value of the attribute at the specified `path` but does not create one if none exists | | MOVE | Moves the attribute with the specified `from` to the specified `path` | | COPY | Copies the attribute at the specified `from` to the specified `path` | ### RegisterCollectorRequest `RegisterCollectorRequest` is used to register a collector with the Fleet Management service, or update the collector’s attributes if the collector is already registered. This request is intended only to be used by the collector itself. It is sent on startup or when the collector’s local configuration changes. Expand table | Field | Type | Label | Description | |-------------------|-------------|----------|-----------------------------------------| | id | string | required | ID of the collector | | local\_attributes | map(string) | optional | Attributes of the collector to register | | name | string | optional | Name of the collector | ### RegisterCollectorResponse The response to a `RegisterCollectorRequest`. This message is empty and the results of the registration are defined by the HTTP status code of the response. ### UpdateCollectorRequest `UpdateCollectorRequest` is the request to update an existing collector. It updates the collector with the exact values provided in the request. If the `enabled` field is not provided, the collector’s existing state persists. All other updates are not selective, and any fields that are not provided are removed. Expand table | Field | Type | Label | Description | |-----------|-----------|-------|-------------------------| | collector | Collector | | Collector to be updated | ## Examples The following JSON files contain sample payloads about a collector, `karasu`. JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```json --- create-collector.json --- { "collector": { "id": "karasu", "remote_attributes": {"myremoteattr": "myremoteval"}, "name": "raven", "enabled": true, "collector_type": "COLLECTOR_TYPE_ALLOY" } } --- update-collector.json --- { "collector": { "id": "karasu", "remote_attributes": {"myremoteattr": "mynewremoteval"}, "enabled": true } } --- get-collector.json --- { "id": "karasu" } --- delete-collector.json --- { "id": "karasu" } ``` You can use these payloads to make the following requests: shell ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```shell $ curl -q \ -d @create-collector.json \ -u "user:pass" \ --header "Content-Type: application/json" \ -X POST https://fleet-management-prod-001.grafana.net/collector.v1.CollectorService/CreateCollector {}% $ curl -q \ -d @update-collector.json \ -u "user:pass" \ --header "Content-Type: application/json" \ -X POST https://fleet-management-prod-001.grafana.net/collector.v1.CollectorService/UpdateCollector {}% $ curl -q \ -d @get-collector.json \ -u "user:pass" \ --header "Content-Type: application/json" \ -X POST https://fleet-management-prod-001.grafana.net/collector.v1.CollectorService/GetCollector {"id":"karasu","remoteAttributes":{"myremoteattr":"mynewremoteval"},"createdAt":"2024-09-02T14:59:13Z","updatedAt":"2024-09-02T16:18:38Z","enabled":true,"collectorType":"COLLECTOR_TYPE_ALLOY"}% $ curl -q \ -d @delete-collector.json \ -u "user:pass" \ --header "Content-Type: application/json" \ -X POST https://fleet-management-prod-001.grafana.net/collector.v1.CollectorService/DeleteCollector {}% $ curl -q \ -d '{}' \ -u "user:pass" \ --header "Content-Type: application/json" \ -X POST https://fleet-management-prod-001.grafana.net/collector.v1.CollectorService/ListCollectors {}% $ curl -q \ -d '{"matchers": ["collector.os=linux"]}' \ -u "user:pass" \ --header "Content-Type: application/json" \ -X POST https://fleet-management-prod-001.grafana.net/collector.v1.CollectorService/ListCollectors {}% ```