Skip to main content
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

NameValue
AuthorizationBearer {API_KEY}
Content-Typeapplication/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 };
  };
}
⌘I