Verify trace ingestion with curl

You can push a test trace to Grafana Cloud Traces using curl to verify that your OpenTelemetry protocol (OTLP) gateway connection and credentials work. This is useful for debugging ingestion issues, testing credentials, or confirming connectivity without setting up a full collector or SDK pipeline.

Before you begin

To complete this procedure, you need:

Your Grafana Cloud OTLP gateway URL, instance ID, and an API key or Cloud Access Policy token with traces:write scope. To find these values, refer to Locate your stack’s URL, user, and password and the OpenTelemetry tile in your Grafana Cloud stack settings.
curl installed on your machine.

OTLP gateway and Tempo query endpoint

Grafana Cloud Traces accepts trace data through the OTLP gateway (for sending traces) endpoint, not the Tempo query endpoint.

OTLP gateway (for sending traces): https://otlp-gateway-<REGION>.grafana.net/otlp/v1/traces
Tempo endpoint (for querying traces): https://<STACK>.grafana.net/tempo

If you send traces to the Tempo query endpoint, they are rejected. Always use the OTLP gateway endpoint when pushing traces from applications, collectors, or scripts.

Copy the exact OTLP gateway URL from the OpenTelemetry tile in your Grafana Cloud stack settings. The URL format varies by region. For details, refer to Determine Grafana Cloud URLs based on region.

Push a test trace

Use the following curl command to push a single test trace to Grafana Cloud Traces through the OTLP gateway.

Before you run the command, update the following values:

Replace <INSTANCE_ID> with your Grafana Cloud instance ID (numeric).
Replace <API_KEY> with your Cloud Access Policy token.
Replace the full OTLP gateway URL with the one from your stack’s OpenTelemetry tile. The example uses otlp-gateway-<REGION>.grafana.net, but your URL may differ depending on when your region was created.
Replace the startTimeUnixNano and endTimeUnixNano values with current timestamps in nanoseconds. The example values must be updated to recent times or the trace may not appear in search results. You can generate a nanosecond timestamp from a terminal with date +%s%N (Linux) or use an online tool such as Epoch Converter.

curl -v -X POST \
  -u '<INSTANCE_ID>:<API_KEY>' \
  -H 'Content-Type: application/json' \
  'https://otlp-gateway-<REGION>.grafana.net/otlp/v1/traces' \
  -d '{
  "resourceSpans": [{
    "resource": {
      "attributes": [{
        "key": "service.name",
        "value": {
          "stringValue": "test-service"
        }
      }]
    },
    "scopeSpans": [{
      "scope": {
        "name": "manual-test",
        "version": "1.0.0"
      },
      "spans": [{
        "traceId": "5B8EFFF798038103D269B633813FC700",
        "spanId": "EEE19B7EC3C1B100",
        "name": "test-span",
        "startTimeUnixNano": 1777060000000000000,
        "endTimeUnixNano": 1777060300000000000,
        "kind": 2,
        "attributes": [{
          "key": "test.attribute",
          "value": {
            "stringValue": "verify-ingestion"
          }
        }]
      }]
    }]
  }]
}'

The -v flag enables verbose output so you can see the HTTP response code. A successful response returns an HTTP 200 status with an empty JSON body ({}).

If the request fails, check the following:

401 Unauthorized: Verify that the instance ID and API key are correct and that the token has traces:write scope.
404 Not Found: Verify that the URL includes /otlp/v1/traces and that you’re using the OTLP gateway endpoint, not the Tempo query endpoint.
Connection errors: Verify that the region in the URL matches your stack’s region.

Verify the trace in Grafana

After pushing the test trace, verify that it arrived in Grafana Cloud Traces.

Open your Grafana Cloud instance.
Navigate to Explore and select the Tempo data source.
Select the TraceQL query type and enter the following query using the trace ID from the curl command:
traceql
```
{ trace:id = "5b8efff798038103d269b633813fc700" }
```
Select Run query. The trace should appear with the test-service service name and test-span span name.