Ingest a batch of traces

Validates the payload, resolves the API key, prices each span, and buffers the rows for a flush to ClickHouse. Fire-and-forget: a 202 means the batch was accepted, not yet durably written.

POST /ingest

Ingest a batch of traces

cURL

curl --request POST \
  --url http://localhost:4000/ingest \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "version": "v1",
  "traces": [
    {
      "traceId": "0192f1c0-1a2b-7c3d-8e4f-1a2b3c4d5e6f",
      "spans": [
        {
          "spanId": "span_1",
          "spanType": "llm",
          "name": "generateText",
          "startTime": 1716566400000,
          "endTime": 1716566401200,
          "parentSpanId": "span_0",
          "status": "ok",
          "errorMessage": "<string>",
          "provider": "openai",
          "modelId": "gpt-4o",
          "usage": {
            "inputTokens": 1200,
            "outputTokens": 350,
            "totalTokens": 1550,
            "reasoningTokens": 1,
            "cachedInputTokens": 1,
            "cacheWriteInputTokens": 1,
            "imageCount": 1,
            "webSearchCount": 1,
            "requestCount": 1
          },
          "ttftMs": 320,
          "chunkOffsets": [
            1
          ],
          "chunkTokens": [
            1
          ],
          "reasoningOffsets": [
            1
          ],
          "reasoningChunkTokens": [
            1
          ],
          "reasoningDurationMs": 1,
          "input": "<string>",
          "output": "<string>",
          "toolCatalog": "<string>",
          "modelCallMs": 1,
          "systemFingerprint": "<string>",
          "safetyMetadata": "<string>",
          "sources": "<string>",
          "rateLimit": {
            "requestsLimit": 1,
            "requestsRemaining": 1,
            "requestsResetMs": 1,
            "tokensLimit": 1,
            "tokensRemaining": 1,
            "tokensResetMs": 1
          },
          "metadata": {
            "environment": "production",
            "region": "us-east-1"
          }
        }
      ],
      "traceName": "classify-email",
      "agentName": "summarizer",
      "workflowName": "deploy-digest",
      "workflowRunId": "run_2024_05_24",
      "sessionId": "session_abc123",
      "metadata": {
        "environment": "production",
        "region": "us-east-1"
      }
    }
  ]
}
'

import requests

url = "http://localhost:4000/ingest"

payload = {
    "version": "v1",
    "traces": [
        {
            "traceId": "0192f1c0-1a2b-7c3d-8e4f-1a2b3c4d5e6f",
            "spans": [
                {
                    "spanId": "span_1",
                    "spanType": "llm",
                    "name": "generateText",
                    "startTime": 1716566400000,
                    "endTime": 1716566401200,
                    "parentSpanId": "span_0",
                    "status": "ok",
                    "errorMessage": "<string>",
                    "provider": "openai",
                    "modelId": "gpt-4o",
                    "usage": {
                        "inputTokens": 1200,
                        "outputTokens": 350,
                        "totalTokens": 1550,
                        "reasoningTokens": 1,
                        "cachedInputTokens": 1,
                        "cacheWriteInputTokens": 1,
                        "imageCount": 1,
                        "webSearchCount": 1,
                        "requestCount": 1
                    },
                    "ttftMs": 320,
                    "chunkOffsets": [1],
                    "chunkTokens": [1],
                    "reasoningOffsets": [1],
                    "reasoningChunkTokens": [1],
                    "reasoningDurationMs": 1,
                    "input": "<string>",
                    "output": "<string>",
                    "toolCatalog": "<string>",
                    "modelCallMs": 1,
                    "systemFingerprint": "<string>",
                    "safetyMetadata": "<string>",
                    "sources": "<string>",
                    "rateLimit": {
                        "requestsLimit": 1,
                        "requestsRemaining": 1,
                        "requestsResetMs": 1,
                        "tokensLimit": 1,
                        "tokensRemaining": 1,
                        "tokensResetMs": 1
                    },
                    "metadata": {
                        "environment": "production",
                        "region": "us-east-1"
                    }
                }
            ],
            "traceName": "classify-email",
            "agentName": "summarizer",
            "workflowName": "deploy-digest",
            "workflowRunId": "run_2024_05_24",
            "sessionId": "session_abc123",
            "metadata": {
                "environment": "production",
                "region": "us-east-1"
            }
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    version: 'v1',
    traces: [
      {
        traceId: '0192f1c0-1a2b-7c3d-8e4f-1a2b3c4d5e6f',
        spans: [
          {
            spanId: 'span_1',
            spanType: 'llm',
            name: 'generateText',
            startTime: 1716566400000,
            endTime: 1716566401200,
            parentSpanId: 'span_0',
            status: 'ok',
            errorMessage: '<string>',
            provider: 'openai',
            modelId: 'gpt-4o',
            usage: {
              inputTokens: 1200,
              outputTokens: 350,
              totalTokens: 1550,
              reasoningTokens: 1,
              cachedInputTokens: 1,
              cacheWriteInputTokens: 1,
              imageCount: 1,
              webSearchCount: 1,
              requestCount: 1
            },
            ttftMs: 320,
            chunkOffsets: [1],
            chunkTokens: [1],
            reasoningOffsets: [1],
            reasoningChunkTokens: [1],
            reasoningDurationMs: 1,
            input: '<string>',
            output: '<string>',
            toolCatalog: '<string>',
            modelCallMs: 1,
            systemFingerprint: '<string>',
            safetyMetadata: '<string>',
            sources: '<string>',
            rateLimit: {
              requestsLimit: 1,
              requestsRemaining: 1,
              requestsResetMs: 1,
              tokensLimit: 1,
              tokensRemaining: 1,
              tokensResetMs: 1
            },
            metadata: {environment: 'production', region: 'us-east-1'}
          }
        ],
        traceName: 'classify-email',
        agentName: 'summarizer',
        workflowName: 'deploy-digest',
        workflowRunId: 'run_2024_05_24',
        sessionId: 'session_abc123',
        metadata: {environment: 'production', region: 'us-east-1'}
      }
    ]
  })
};

fetch('http://localhost:4000/ingest', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "4000",
  CURLOPT_URL => "http://localhost:4000/ingest",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'version' => 'v1',
    'traces' => [
        [
                'traceId' => '0192f1c0-1a2b-7c3d-8e4f-1a2b3c4d5e6f',
                'spans' => [
                                [
                                                                'spanId' => 'span_1',
                                                                'spanType' => 'llm',
                                                                'name' => 'generateText',
                                                                'startTime' => 1716566400000,
                                                                'endTime' => 1716566401200,
                                                                'parentSpanId' => 'span_0',
                                                                'status' => 'ok',
                                                                'errorMessage' => '<string>',
                                                                'provider' => 'openai',
                                                                'modelId' => 'gpt-4o',
                                                                'usage' => [
                                                                                                                                'inputTokens' => 1200,
                                                                                                                                'outputTokens' => 350,
                                                                                                                                'totalTokens' => 1550,
                                                                                                                                'reasoningTokens' => 1,
                                                                                                                                'cachedInputTokens' => 1,
                                                                                                                                'cacheWriteInputTokens' => 1,
                                                                                                                                'imageCount' => 1,
                                                                                                                                'webSearchCount' => 1,
                                                                                                                                'requestCount' => 1
                                                                ],
                                                                'ttftMs' => 320,
                                                                'chunkOffsets' => [
                                                                                                                                1
                                                                ],
                                                                'chunkTokens' => [
                                                                                                                                1
                                                                ],
                                                                'reasoningOffsets' => [
                                                                                                                                1
                                                                ],
                                                                'reasoningChunkTokens' => [
                                                                                                                                1
                                                                ],
                                                                'reasoningDurationMs' => 1,
                                                                'input' => '<string>',
                                                                'output' => '<string>',
                                                                'toolCatalog' => '<string>',
                                                                'modelCallMs' => 1,
                                                                'systemFingerprint' => '<string>',
                                                                'safetyMetadata' => '<string>',
                                                                'sources' => '<string>',
                                                                'rateLimit' => [
                                                                                                                                'requestsLimit' => 1,
                                                                                                                                'requestsRemaining' => 1,
                                                                                                                                'requestsResetMs' => 1,
                                                                                                                                'tokensLimit' => 1,
                                                                                                                                'tokensRemaining' => 1,
                                                                                                                                'tokensResetMs' => 1
                                                                ],
                                                                'metadata' => [
                                                                                                                                'environment' => 'production',
                                                                                                                                'region' => 'us-east-1'
                                                                ]
                                ]
                ],
                'traceName' => 'classify-email',
                'agentName' => 'summarizer',
                'workflowName' => 'deploy-digest',
                'workflowRunId' => 'run_2024_05_24',
                'sessionId' => 'session_abc123',
                'metadata' => [
                                'environment' => 'production',
                                'region' => 'us-east-1'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:4000/ingest"

	payload := strings.NewReader("{\n  \"version\": \"v1\",\n  \"traces\": [\n    {\n      \"traceId\": \"0192f1c0-1a2b-7c3d-8e4f-1a2b3c4d5e6f\",\n      \"spans\": [\n        {\n          \"spanId\": \"span_1\",\n          \"spanType\": \"llm\",\n          \"name\": \"generateText\",\n          \"startTime\": 1716566400000,\n          \"endTime\": 1716566401200,\n          \"parentSpanId\": \"span_0\",\n          \"status\": \"ok\",\n          \"errorMessage\": \"<string>\",\n          \"provider\": \"openai\",\n          \"modelId\": \"gpt-4o\",\n          \"usage\": {\n            \"inputTokens\": 1200,\n            \"outputTokens\": 350,\n            \"totalTokens\": 1550,\n            \"reasoningTokens\": 1,\n            \"cachedInputTokens\": 1,\n            \"cacheWriteInputTokens\": 1,\n            \"imageCount\": 1,\n            \"webSearchCount\": 1,\n            \"requestCount\": 1\n          },\n          \"ttftMs\": 320,\n          \"chunkOffsets\": [\n            1\n          ],\n          \"chunkTokens\": [\n            1\n          ],\n          \"reasoningOffsets\": [\n            1\n          ],\n          \"reasoningChunkTokens\": [\n            1\n          ],\n          \"reasoningDurationMs\": 1,\n          \"input\": \"<string>\",\n          \"output\": \"<string>\",\n          \"toolCatalog\": \"<string>\",\n          \"modelCallMs\": 1,\n          \"systemFingerprint\": \"<string>\",\n          \"safetyMetadata\": \"<string>\",\n          \"sources\": \"<string>\",\n          \"rateLimit\": {\n            \"requestsLimit\": 1,\n            \"requestsRemaining\": 1,\n            \"requestsResetMs\": 1,\n            \"tokensLimit\": 1,\n            \"tokensRemaining\": 1,\n            \"tokensResetMs\": 1\n          },\n          \"metadata\": {\n            \"environment\": \"production\",\n            \"region\": \"us-east-1\"\n          }\n        }\n      ],\n      \"traceName\": \"classify-email\",\n      \"agentName\": \"summarizer\",\n      \"workflowName\": \"deploy-digest\",\n      \"workflowRunId\": \"run_2024_05_24\",\n      \"sessionId\": \"session_abc123\",\n      \"metadata\": {\n        \"environment\": \"production\",\n        \"region\": \"us-east-1\"\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:4000/ingest")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"version\": \"v1\",\n  \"traces\": [\n    {\n      \"traceId\": \"0192f1c0-1a2b-7c3d-8e4f-1a2b3c4d5e6f\",\n      \"spans\": [\n        {\n          \"spanId\": \"span_1\",\n          \"spanType\": \"llm\",\n          \"name\": \"generateText\",\n          \"startTime\": 1716566400000,\n          \"endTime\": 1716566401200,\n          \"parentSpanId\": \"span_0\",\n          \"status\": \"ok\",\n          \"errorMessage\": \"<string>\",\n          \"provider\": \"openai\",\n          \"modelId\": \"gpt-4o\",\n          \"usage\": {\n            \"inputTokens\": 1200,\n            \"outputTokens\": 350,\n            \"totalTokens\": 1550,\n            \"reasoningTokens\": 1,\n            \"cachedInputTokens\": 1,\n            \"cacheWriteInputTokens\": 1,\n            \"imageCount\": 1,\n            \"webSearchCount\": 1,\n            \"requestCount\": 1\n          },\n          \"ttftMs\": 320,\n          \"chunkOffsets\": [\n            1\n          ],\n          \"chunkTokens\": [\n            1\n          ],\n          \"reasoningOffsets\": [\n            1\n          ],\n          \"reasoningChunkTokens\": [\n            1\n          ],\n          \"reasoningDurationMs\": 1,\n          \"input\": \"<string>\",\n          \"output\": \"<string>\",\n          \"toolCatalog\": \"<string>\",\n          \"modelCallMs\": 1,\n          \"systemFingerprint\": \"<string>\",\n          \"safetyMetadata\": \"<string>\",\n          \"sources\": \"<string>\",\n          \"rateLimit\": {\n            \"requestsLimit\": 1,\n            \"requestsRemaining\": 1,\n            \"requestsResetMs\": 1,\n            \"tokensLimit\": 1,\n            \"tokensRemaining\": 1,\n            \"tokensResetMs\": 1\n          },\n          \"metadata\": {\n            \"environment\": \"production\",\n            \"region\": \"us-east-1\"\n          }\n        }\n      ],\n      \"traceName\": \"classify-email\",\n      \"agentName\": \"summarizer\",\n      \"workflowName\": \"deploy-digest\",\n      \"workflowRunId\": \"run_2024_05_24\",\n      \"sessionId\": \"session_abc123\",\n      \"metadata\": {\n        \"environment\": \"production\",\n        \"region\": \"us-east-1\"\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:4000/ingest")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"version\": \"v1\",\n  \"traces\": [\n    {\n      \"traceId\": \"0192f1c0-1a2b-7c3d-8e4f-1a2b3c4d5e6f\",\n      \"spans\": [\n        {\n          \"spanId\": \"span_1\",\n          \"spanType\": \"llm\",\n          \"name\": \"generateText\",\n          \"startTime\": 1716566400000,\n          \"endTime\": 1716566401200,\n          \"parentSpanId\": \"span_0\",\n          \"status\": \"ok\",\n          \"errorMessage\": \"<string>\",\n          \"provider\": \"openai\",\n          \"modelId\": \"gpt-4o\",\n          \"usage\": {\n            \"inputTokens\": 1200,\n            \"outputTokens\": 350,\n            \"totalTokens\": 1550,\n            \"reasoningTokens\": 1,\n            \"cachedInputTokens\": 1,\n            \"cacheWriteInputTokens\": 1,\n            \"imageCount\": 1,\n            \"webSearchCount\": 1,\n            \"requestCount\": 1\n          },\n          \"ttftMs\": 320,\n          \"chunkOffsets\": [\n            1\n          ],\n          \"chunkTokens\": [\n            1\n          ],\n          \"reasoningOffsets\": [\n            1\n          ],\n          \"reasoningChunkTokens\": [\n            1\n          ],\n          \"reasoningDurationMs\": 1,\n          \"input\": \"<string>\",\n          \"output\": \"<string>\",\n          \"toolCatalog\": \"<string>\",\n          \"modelCallMs\": 1,\n          \"systemFingerprint\": \"<string>\",\n          \"safetyMetadata\": \"<string>\",\n          \"sources\": \"<string>\",\n          \"rateLimit\": {\n            \"requestsLimit\": 1,\n            \"requestsRemaining\": 1,\n            \"requestsResetMs\": 1,\n            \"tokensLimit\": 1,\n            \"tokensRemaining\": 1,\n            \"tokensResetMs\": 1\n          },\n          \"metadata\": {\n            \"environment\": \"production\",\n            \"region\": \"us-east-1\"\n          }\n        }\n      ],\n      \"traceName\": \"classify-email\",\n      \"agentName\": \"summarizer\",\n      \"workflowName\": \"deploy-digest\",\n      \"workflowRunId\": \"run_2024_05_24\",\n      \"sessionId\": \"session_abc123\",\n      \"metadata\": {\n        \"environment\": \"production\",\n        \"region\": \"us-east-1\"\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

202

Example

{
  "accepted": 3
}

Authorizations

bearerAuthapiKeyAuth

Authorization · string · header · required

Send your API key as Authorization: Bearer fl_….

Body

application/json

A versioned batch of traces.

version · string · required

Wire contract version.

Allowed value: "v1"

Example:

"v1"

traces · object[] · required

Required array length: 1 - 1000 elements

Show child attributes

Response

202

application/json

Batch accepted into the write buffer.

accepted · integer · required

Number of span rows accepted.

Example:

3