The IONOS CLOUD Tracing API collects OpenTelemetry Protocol (OTLP) traces from any compatible source. It routes them through tenant-isolated pipelines. Each pipeline exposes a Grafana endpoint for querying and correlating traces with logs and metrics. If you are new to the Tracing API, see What Can You Do with the Tracing API?. If you manage observability infrastructure, see Tracing API Workflows.

Using the Tracing API, you can:

• Create and manage pipelines: Provision tenant-isolated pipelines that define the OTLP ingestion protocol and endpoint for your trace data.
• Select the OTLP protocol: Choose between OTLP HTTP and OTLP gRPC (Google Remote Procedure Call) per pipeline to match your exporter configuration.
• Access the Grafana endpoint: Retrieve the Grafana instance URL for each pipeline to query and visualize collected traces.
• Rotate pipeline keys: Generate a new authentication key for a pipeline to invalidate the previous one.

The Tracing API is available at the following endpoints.

To authenticate with the API, see Authentication. To make your first API call, see Quick Start.

• Protocol support: The IONOS CLOUD Tracing API supports OTLP HTTP and OTLP gRPC protocols. You select one protocol per pipeline. Changing it later with Ensure Pipeline reprovisions the ingestion route behind the same DNS name and may temporarily interrupt ingestion while you reconfigure your exporter.
• Async provisioning: Create and delete operations are asynchronous. Poll Retrieve Pipeline until metadata.state reaches AVAILABLE before connecting exporters.
• Ensure semantics: PUT operations use full-replacement semantics. Both properties.name and properties.protocol are required in every PUT request. The API returns 400 if either is missing.
• One-time key retrieval: The API returns the authentication key (metadata.key) only in the 201 create response and in Rotate Key responses. Subsequent GET responses omit the key.
• Pagination: List operations use offset and limit parameters. The default page size is 100. The maximum is 1000. To retrieve the next page, increment offset by the limit value, or follow _links.next when it is present in the response.

• Multi-source trace visibility: The Tracing API accepts OTLP traces from IONOS CLOUD workloads, on-premises environments, and other clouds. You receive one Grafana endpoint per pipeline to query and correlate all collected traces with logs and metrics.
• Regional data colocation: Each pipeline is provisioned in one of nine metro locations. You reduce latency and meet local data-storage requirements by placing pipelines in the region closest to your workloads.
• Secure-by-default ingestion: Each pipeline carries a unique authentication key. The API returns this key only on creation and rotation. You can rotate the key at any time without reprovisioning the pipeline, limiting the blast radius of a compromised credential.
• Protocol flexibility: Each pipeline exposes either OTLP HTTP or OTLP gRPC, and the ingestion DNS name remains stable when you switch. You reconfigure only your exporter, not the pipeline endpoint.

All requests to the Tracing API require a Bearer token in the Authorization header:

Authorization: Bearer <your-token>

To generate a token, use IONOS CLOUD Authentication API. The Tracing API supports only token-based authentication (tokenAuth). Basic authentication is not supported.

List your pipelines to confirm your access token works. The following example uses the Frankfurt (de-fra) endpoint:

curl -X GET "https://tracing.de-fra.ionos.com/pipelines" \
  -H "Authorization: Bearer $IONOS_TOKEN"

A successful response returns HTTP 200 with a paginated items array. If you have no pipelines yet, items is empty. To connect to a specific region, replace the endpoint host with the corresponding regional host from Endpoints. To provision your first pipeline, see Deploy a Pipeline.

Use these end-to-end workflows to deploy, connect, and operate resources using the IONOS CLOUD Tracing API.

• Deploy a pipeline: Plan your pipeline configuration and provision it through to the AVAILABLE state.
• Connect to your pipeline: Retrieve the OTLP ingestion endpoint and Grafana endpoint, and connect your exporter using the credentials from deploy.
• Operate a pipeline: Manage a running pipeline with day-to-day operations and deprovision it when no longer needed.

  Note: If an operation returns an error, refer to the response details of each operation for API-specific error codes. For generic HTTP status codes used across IONOS CLOUD APIs, see HTTP Status Codes.

Use this workflow to plan and provision a new pipeline.

Prerequisites

• An access token that authenticates your API requests. For more information, see Authentication.

  Step 1: Choose Protocol

  Choose the OTLP protocol for your pipeline.
• otlp-http: Use for OTLP HTTP exporters. Exporters must append /v1/traces to the otlpEndpoint when sending traces.
• otlp-grpc: Use for OTLP gRPC exporters. Exporters connect to the otlpEndpoint on port 443 without a URL path.

  Note: Changing the protocol after creation reprovisions the ingestion route behind the same DNS name and may temporarily interrupt ingestion while you reconfigure your exporter.

  Step 2: Provision a Pipeline

1. Create the pipeline:
   • API: Create Pipeline
   • Action: Provide the required fields: properties.name (1-36 characters) and properties.protocol (otlp-grpc or otlp-http). Example request body:

     {
     "properties": {
      "name": "trace-pipeline-prod",
      "protocol": "otlp-grpc"
     }
     }
     

   • Result: The API returns HTTP 201 with the pipeline id and metadata.state as PROVISIONING. Note the id and metadata.key. You need them in every subsequent operation.

     Note:

     • Pipeline provisioning is asynchronous. Poll Retrieve Pipeline until metadata.state is AVAILABLE.
     • Once AVAILABLE, metadata.otlpEndpoint contains the stable ingestion endpoint and metadata.grafanaEndpoint contains the Grafana URL.
     • Save metadata.key: the API returns it only in this response and in the Rotate Key response. You cannot retrieve it later.
     • If metadata.state returns FAILED, retrieve the pipeline using Retrieve Pipeline and inspect metadata.statusMessage for details. Submit a new Create Pipeline request to retry. Failed pipelines cannot be recovered in place.

Next steps: To connect your exporter to the pipeline, see Connect to Your Pipeline.

Use this workflow to retrieve the pipeline ingestion endpoint and connect your OTLP exporter.

Prerequisites

• Ensure the pipeline is in the AVAILABLE state.
• You must have the id (UUID) of the pipeline. You receive this when you complete the Deploy a Pipeline workflow.
• You must have the metadata.key you saved in Step 2 of the Deploy a Pipeline workflow.

  Step 1: Retrieve the Connection Details

• API: Retrieve Pipeline
• Path Parameter pipelineId: The UUID of your pipeline.
• Action: Retrieve the pipeline to obtain the OTLP ingestion endpoint and Grafana URL.
• Result: The API returns HTTP 200 with the full pipeline object. Note metadata.otlpEndpoint and metadata.grafanaEndpoint for Step 2.

  Step 2: Connect Your OTLP Exporter

  Use the following details to configure your OTLP exporter:

  Property	Value
  Endpoint	metadata.otlpEndpoint from Step 1
  Authorization	Bearer <metadata.key> from the deploy or key rotation response
  Protocol	Matches properties.protocol: otlp-http or otlp-grpc

  Note: For OTLP HTTP exporters, append /v1/traces to the otlpEndpoint. For OTLP gRPC exporters, use the otlpEndpoint on port 443 without a URL path.

Next steps: For day-2 tasks on a running pipeline, see Operate a Pipeline.

Use this workflow to perform day-2 tasks on a running pipeline.

Note: All pipeline updates use Ensure (full-replacement) semantics. Retrieve the full pipeline configuration before you submit any PUT request. Any field omitted is set to its schema default or cleared to empty. It does not retain its previous value.

Prerequisites

• Ensure the pipeline is in the AVAILABLE state.
• You must have the id (UUID) of the pipeline. You receive this when you complete Deploy a Pipeline.

  Update Pipeline Configuration

  Change the pipeline name or OTLP protocol using the Ensure operation.
• API: Ensure Pipeline
• Path Parameter pipelineId: The UUID of the pipeline.
• Action: Submit the full pipeline object with updated properties.name or properties.protocol. Both fields must be present in every request.
• Result: The API returns HTTP 200 and the pipeline transitions to UPDATING, then back to AVAILABLE. Poll Retrieve Pipeline on metadata.state to confirm.

  Note: If metadata.state returns FAILED, retrieve the pipeline using Retrieve Pipeline and inspect metadata.statusMessage for details. Submit a new Ensure Pipeline request to retry.

  Rotate the Pipeline Key

  Generate a new authentication key to invalidate the current key.

• API: Rotate Key
• Path Parameter pipelineId: The UUID of the pipeline.
• Action: Submit the rotate key request. No request body is required.
• Result: The API returns HTTP 201 with the new key value. Save this key: the API returns it only in this response, and you cannot retrieve it again.

  Note: Update your OTLP exporter configuration with the new key immediately after rotation. Rotation invalidates the previous key, and exporters using it stop sending traces.

  Deprovision the Pipeline

  Warning: Deleting a pipeline is irreversible. The delete operation permanently removes the pipeline and all associated ingestion configuration.

Deprovision the pipeline when it is no longer needed to release resources.

• API: Delete Pipeline
• Path Parameter pipelineId: The UUID of the pipeline to delete.
• Action: Submit the delete request to permanently remove the pipeline.
• Result: The API returns HTTP 202 and accepts the delete request. Deletion is asynchronous, and it permanently removes the pipeline and all associated resources. You cannot recover them.

  Note: If metadata.state returns FAILED instead of the pipeline being removed, retrieve the pipeline using Retrieve Pipeline and inspect metadata.statusMessage for details. Submit a new Delete Pipeline request to retry.

Configure the tracing pipeline that defines the OTLP ingestion protocol and endpoint for tenant-isolated trace collection. Use these operations to create, retrieve, update, and delete pipelines. Changing protocol reprovisions the ingestion route behind the same DNS name and requires clients to switch exporter configuration between OTLP HTTP and OTLP gRPC.

This tag groups all operations for pipelines.

Rotate the pipeline key to invalidate the previous one. The key rotation operation returns the new key only once. You cannot retrieve it again. This tag groups all operations for key.