Explorar documentación

Referencia de la APIActualizado el 29 de julio de 2026Revisado por los equipos editorial y de producto de Telemetry6 min de lectura

Usa esta documentación con tu agente de programación

Abra un paquete de mensajes enfocados para Claude Code, Codex, Cursor u otro agente de codificación, luego adáptelo al flujo de trabajo que se describe aquí.

Abrir el paquete de instrucciones Conecta telemetría real

En esta página

Ejemplo de uso con cURL
Usando el JavaScript SDK
Consulta asíncrona
como funciona
API Referencia
Consulta asíncrona con cURL
Ejemplo: exportar una tabla completa
Límite SDK
Errores comunes

Consulta

La consulta API le permite ejecutar SQL con sus datos de Telemetry.

ENVÍO https://api.telemetry.sh/query

Encabezados

Nombre	Tipo	Descripción
Tipo de contenido	Cadena de texto	aplicación/json
Autorización	Cadena de texto	Su clave API, ya sea como clave sin formato o como `Bearer <key>`

Cuerpo

Nombre	Tipo	Requerido	Descripción
consulta	Cadena de texto	si	Consulta SQL para ejecutar.
tiempo real	Booleano	No	El valor predeterminado es `true`. Pasado al servicio de consultas.
json	Booleano	No	El valor predeterminado es `true`. Pasado al servicio de consultas.

Respuesta correcta, 200 OK

{
  "status": "success",
  "data": [
    {
      "city": "paris",
      "average_price": 42.0
    }
  ],
  "key_order": ["city", "average_price"]
}

data contiene las filas de resultados. key_order conserva el orden de las columnas del resultado de la consulta.

Ejemplo de uso con cURL

Esta solicitud cURL consulta el precio medio de los viajes por ciudad en uber_rides:

QUERY=$(cat <<'SQL'
SELECT
  city,
  AVG(price) AS average_price
FROM
  uber_rides
GROUP BY
  city
LIMIT
  10000;
SQL
)

curl -X POST https://api.telemetry.sh/query \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d "$(jq -n --arg query "$QUERY" '{query: $query, realtime: true, json: true}')"

Usando el JavaScript SDK

Recomendamos utilizar los SDK para una mejor experiencia de desarrollador:

import telemetry from "telemetry-sh";

telemetry.init("YOUR_API_KEY");

const results =
  await telemetry.query(`
    SELECT
      city,
      AVG(price)
    FROM
      uber_rides
    GROUP BY
      city
  `);

Consulta asíncrona

Los resultados JSON pequeños se devuelven directamente en result, con data y key_order. Los resultados JSON grandes y las exportaciones Parquet usan download_url. Una respuesta completada solo necesita una de estas opciones; los resultados directos no requieren una URL de descarga ni sus campos de caducidad. Si download_url_expired es verdadero, inicia otra consulta. Los campos de caducidad son opcionales.

Esto es especialmente útil para exportar tablas enteras, ejecutar agregaciones pesadas o descargar resultados como archivos JSON o Parquet.

como funciona

Inicio — POST su consulta a /query/async. El servidor devuelve un job_id y un status_url.
Encuesta — GET o status_url para comprobar el progreso.
Lee el resultado directo en result o descarga el archivo de download_url.

API Referencia

Iniciar una consulta asíncrona

ENVÍO https://api.telemetry.sh/query/async

Encabezados

Nombre	Tipo	Descripción
Tipo de contenido	Cadena de texto	aplicación/json
Autorización	Cadena de texto	Su clave API, ya sea como clave sin formato o como `Bearer <key>`

Cuerpo

Nombre	Tipo	Requerido	Descripción
consulta	Cadena de texto	si	Consulta SQL para ejecutar.
tiempo real	Booleano	No	El valor predeterminado es `true`. Pasado al servicio de consultas.
json	Booleano	No	El valor predeterminado es `true`. Pasado al servicio de consultas.
formato	Cadena de texto	No	Formato de resultado: `"json"` (predeterminado) o `"parquet"`.

Respuesta (202 Aceptadas)

{
  "status": "accepted",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "format": "json",
  "status_url": "/query/async/550e8400-e29b-41d4-a716-446655440000"
}

Estado de la consulta de encuesta

OBTENER https://api.telemetry.sh/query/async/{job_id}

Encabezados

Nombre	Tipo	Descripción
Autorización	Cadena de texto	Su clave API, ya sea como clave sin formato o como `Bearer <key>`

Respuesta (200 OK)

Resultado JSON directo

{
  "status": "success",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "query_status": "completed",
  "format": "json",
  "progress_pct": 100,
  "result": {
    "data": [{ "events": 7 }],
    "key_order": ["events"]
  }
}

Resultado disponible para descargar

{
  "status": "success",
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "query_status": "completed",
  "format": "json",
  "progress_pct": 100,
  "message": "Query completed",
  "created_at": "2025-02-24T12:00:00Z",
  "completed_at": "2025-02-24T12:00:05Z",
  "download_url": "https://storage.example.com/results/...",
  "download_url_expires_in_seconds": 3600
}

Cuando format es "json", el archivo descargado contiene metadatos de consulta más la forma de resultado de consulta estándar en result:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "format": "json",
  "result": {
    "data": [
      {
        "city": "paris",
        "average_price": 42.0
      }
    ],
    "key_order": ["city", "average_price"]
  }
}

El campo query_status será uno de:

Estado	Descripción
`queued`	La consulta está esperando ser ejecutada.
`running`	La consulta se está ejecutando actualmente.
`completed`	Resultados disponibles en `result` o mediante `download_url`.
`failed`	La consulta falló. Verifique el campo `error`.
`cancelled`	La consulta se canceló.

Consulta asíncrona con cURL

# 1. Start the async query
QUERY='SELECT * FROM uber_rides'
RESPONSE=$(curl --fail-with-body -sS --max-time 30 https://api.telemetry.sh/query/async \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d "$(jq -n --arg query "$QUERY" '{query: $query, format: "json", realtime: true, json: true}')") || exit 1
STATUS_URL="https://api.telemetry.sh$(echo "$RESPONSE" | jq -r '.status_url')"

# 2. Poll for at most ten minutes
DEADLINE=$((SECONDS + 600))
while [ "$SECONDS" -lt "$DEADLINE" ]; do
  STATUS=$(curl --fail-with-body -sS --max-time 30 -H "Authorization: $API_KEY" "$STATUS_URL") || exit 1
  QUERY_STATUS=$(echo "$STATUS" | jq -r '.query_status')

  if [ "$QUERY_STATUS" = "completed" ]; then
    if echo "$STATUS" | jq -e '.download_url_expired == true' >/dev/null; then
      echo "Result expired. Start a new query."
      exit 1
    elif echo "$STATUS" | jq -e '.result | type == "object"' >/dev/null; then
      echo "$STATUS" | jq '{result: .result}' > results.json
    else
      DOWNLOAD_URL=$(echo "$STATUS" | jq -r '.download_url // empty')
      if [ -z "$DOWNLOAD_URL" ]; then
        echo "Completed response has neither a result nor an active download URL."
        exit 1
      fi
      curl --fail-with-body -sS --max-time 300 -o results.json "$DOWNLOAD_URL" || exit 1
    fi
    # Both branches have the same result shape, including an empty data array.
    jq '.result' results.json
    exit 0
  elif [ "$QUERY_STATUS" = "failed" ] || [ "$QUERY_STATUS" = "cancelled" ]; then
    echo "Query $QUERY_STATUS: $(echo "$STATUS" | jq -r '.error // .message')"
    exit 1
  elif [ "$QUERY_STATUS" != "queued" ] && [ "$QUERY_STATUS" != "running" ]; then
    echo "Unexpected query status: $QUERY_STATUS"
    exit 1
  fi
  sleep 5
done
echo "Query polling timed out."
exit 1

Ejemplo: exportar una tabla completa

La consulta asíncrona API es ideal para exportaciones de tablas completas. Como no hay límite de filas para consultas asíncronas, puede exportar todo y descargar el resultado como un solo archivo.

# Start the export as Parquet
QUERY='SELECT * FROM uber_rides'

RESPONSE=$(curl -s -X POST https://api.telemetry.sh/query/async \
  -H "Content-Type: application/json" \
  -H "Authorization: $API_KEY" \
  -d "$(jq -n --arg query "$QUERY" '{query: $query, format: "parquet", realtime: true, json: true}')")

STATUS_URL="https://api.telemetry.sh$(echo "$RESPONSE" | jq -r '.status_url')"

# Poll until complete
while true; do
  STATUS=$(curl -s -H "Authorization: $API_KEY" "$STATUS_URL")
  QUERY_STATUS=$(echo "$STATUS" | jq -r '.query_status')

  if [ "$QUERY_STATUS" = "completed" ]; then
    DOWNLOAD_URL=$(echo "$STATUS" | jq -r '.download_url // empty')
    if [ -z "$DOWNLOAD_URL" ]; then
      echo "Export completed, but no active download URL is available."
      exit 1
    fi
    curl -o uber_rides_export.parquet "$DOWNLOAD_URL"
    echo "Export complete: uber_rides_export.parquet"
    break
  elif [ "$QUERY_STATUS" = "failed" ]; then
    echo "Export failed: $(echo "$STATUS" | jq -r '.error // .message')"
    exit 1
  fi

  sleep 5
done

Límite SDK

El método query del JavaScript SDK actual llama al /query interactivo punto final. No inicia /query/async, no sondea status_url, no aplica una tiempo de espera del trabajo asincrónico o descargue el artefacto terminado.

Utilice el flujo de inicio, sondeo y descarga de HTTP anterior para JSON o Parquet grandes. exportaciones. Un contenedor de aplicación puede encapsular esas tres operaciones, pero aún debería imponer una fecha límite total de votación, detenerse en failed y tratar una Expiró download_url como una nueva exportación en lugar de volver a intentar la descarga anterior. indefinidamente.

Errores comunes

400 Bad Request si el cuerpo JSON no es válido
400 Bad Request si query falta o está vacío
401 Unauthorized si la clave API falta o no es válida
402 Payment Required si la cuenta está bloqueada por un cheque de muro de pago
429 Too Many Requests si la clave API excede el límite de velocidad de la puerta de enlace

Función relacionada

Ejecute DataFusion SQL de solo lectura sobre tablas de eventos estructurados y reutilice el resultado.

Explorar Consulta SQL API Historias de clientes

Autores de la página y referencias

El equipo editorial de Telemetry es responsable de esta explicación; el equipo de producto revisa el comportamiento, los ejemplos y las limitaciones.

Cómo revisamos nuestra documentación

Referencia SQL de Apache DataFusion