Custom Logs with cURL

Use the custom logging endpoint to log any operation to Helicone - database queries, API calls, ML inference, or any other operation you want to track.

Example

curl -X POST https://api.worker.helicone.ai/custom/v1/log \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
  "providerRequest": {
    "url": "custom-model-nopath",
    "json": {
      "_type": "data",
      "name": "user_query",
      "query": "SELECT * FROM users WHERE active = true"
    }
  },
  "providerResponse": {
    "json": {
      "_type": "data",
      "name": "user_query",
      "status": "success",
      "data": [...]
    },
    "status": 200
  },
  "timing": {
    "startTime": { "seconds": 1625686222, "milliseconds": 500 },
    "endTime": { "seconds": 1625686223, "milliseconds": 750 }
  }
}'

Understanding the Structure

All custom logs have three main parts:

1. Provider Request

What you’re about to do. Must include:

url: "custom-model-nopath" - Required for custom logs
json._type: "data" - Identifies this as a custom data log
json.name - A descriptive name for your operation
Any custom fields you want to track (query, endpoint, model, etc.)

2. Provider Response

What happened. Should include:

json._type: "data" - Identifies this as a custom data response
json.name - Same name as the request
json.status - Success or error state
status - HTTP status code (typically 200)
Any result data you want to track

3. Timing

When it happened:

startTime - When the operation began (Unix epoch)
endTime - When the operation completed (Unix epoch)

Examples

Database Query

curl -X POST https://api.worker.helicone.ai/custom/v1/log \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
  "providerRequest": {
    "url": "custom-model-nopath",
    "json": {
      "_type": "data",
      "name": "user_query",
      "query": "SELECT * FROM users WHERE active = true",
      "database": "production"
    }
  },
  "providerResponse": {
    "json": {
      "_type": "data",
      "name": "user_query",
      "status": "success",
      "count": 2,
      "duration": "45ms"
    },
    "status": 200
  },
  "timing": {
    "startTime": { "seconds": 1625686222, "milliseconds": 500 },
    "endTime": { "seconds": 1625686223, "milliseconds": 750 }
  }
}'

External API Call

curl -X POST https://api.worker.helicone.ai/custom/v1/log \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
  "providerRequest": {
    "url": "custom-model-nopath",
    "json": {
      "_type": "data",
      "name": "external_api_call",
      "endpoint": "https://api.example.com/users",
      "method": "GET"
    }
  },
  "providerResponse": {
    "json": {
      "_type": "data",
      "name": "external_api_call",
      "status": "success",
      "result": { "total": 150, "page": 1 }
    },
    "status": 200
  },
  "timing": {
    "startTime": { "seconds": 1625686222, "milliseconds": 500 },
    "endTime": { "seconds": 1625686223, "milliseconds": 750 }
  }
}'

ML Model Inference

curl -X POST https://api.worker.helicone.ai/custom/v1/log \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
  "providerRequest": {
    "url": "custom-model-nopath",
    "json": {
      "_type": "data",
      "name": "ml_inference",
      "model": "custom-classifier-v2",
      "input_features": { "text": "This is a sample text" }
    }
  },
  "providerResponse": {
    "json": {
      "_type": "data",
      "name": "ml_inference",
      "status": "success",
      "result": {
        "classification": "positive",
        "confidence": 0.92
      }
    },
    "status": 200
  },
  "timing": {
    "startTime": { "seconds": 1625686222, "milliseconds": 500 },
    "endTime": { "seconds": 1625686223, "milliseconds": 750 }
  }
}'

API Reference

Endpoint

POST https://api.worker.helicone.ai/custom/v1/log

Note: The endpoint may vary depending on your Helicone setup:

US: https://api.us.helicone.ai/custom/v1/log
Elsewhere: https://api.helicone.ai/custom/v1/log

Headers

Name	Value
Authorization	Bearer `{API_KEY}`
Content-Type	application/json

Request Body

{
  providerRequest: {
    url: "custom-model-nopath";
    json: {
      _type: "data";
      name: string;
      [key: string]: any;  // Add any custom fields
    };
    meta?: Record<string, string>;  // Optional metadata
  };
  providerResponse: {
    json: {
      _type?: "data";
      name?: string;
      [key: string]: any;  // Add any custom fields
    };
    status: number;
    headers?: Record<string, string>;
  };
  timing: {
    startTime: { seconds: number; milliseconds: number };
    endTime: { seconds: number; milliseconds: number };
  };
}

Getting Started

AI Gateway

Observability & Analytics

Prompt Management

Legacy Integrations

References

Example

Understanding the Structure

1. Provider Request

2. Provider Response

3. Timing

Examples

Database Query

External API Call

ML Model Inference

API Reference

Endpoint

Headers

Request Body

​Example

​Understanding the Structure

​1. Provider Request

​2. Provider Response

​3. Timing

​Examples

​Database Query

​External API Call

​ML Model Inference

​API Reference

​Endpoint

​Headers

​Request Body

Example

Understanding the Structure

1. Provider Request

2. Provider Response

3. Timing

Examples

Database Query

External API Call

ML Model Inference

API Reference

Endpoint

Headers

Request Body