> This page is for version v5.0 (default). > For other versions, use one of these documentation indexes: > - v5.0 (default): https://humanloop.com/docs/v5/llms.txt > - v4.0: https://humanloop.com/docs/v4/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://humanloop.com/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://humanloop.com/docs/_mcp/server. # Log to a Tool POST https://api.humanloop.com/v5/tools/log Content-Type: application/json Log to a Tool. You can use query parameters `version_id`, or `environment`, to target an existing version of the Tool. Otherwise the default deployed version will be chosen. Instead of targeting an existing version explicitly, you can instead pass in Tool details in the request body. In this case, we will check if the details correspond to an existing version of the Tool, if not we will create a new version. This is helpful in the case where you are storing or deriving your Tool details in code. Reference: https://humanloop.com/docs/api/tools/log ## Authentication - `X-API-KEY` header (required) — API Key authentication via header ## Request ### Query parameters - `version_id` (string, optional) — A specific Version ID of the Tool to log to. - `environment` (string, optional) — Name of the Environment identifying a deployed version to log to. ### Body (application/json) This endpoint expects an object. - `path` (string, optional) — Path of the Tool, including the name. This locates the Tool in the Humanloop filesystem and is used as as a unique identifier. For example: `folder/name` or just `name`. - `id` (string, optional) — ID for an existing Tool. - `tool` (ToolKernelRequest, optional) — Details of your Tool. A new Tool version will be created if the provided details are new. - `start_time` (datetime, optional) — When the logged event started. - `end_time` (datetime, optional) — When the logged event ended. - `output` (string, optional) — Generated output from your model for the provided inputs. Can be `None` if logging an error, or if creating a parent Log with the intention to populate it later. - `created_at` (datetime, optional) — User defined timestamp for when the log was created. - `error` (string, optional) — Error message if the log is an error. - `provider_latency` (double, optional) — Duration of the logged event in seconds. - `stdout` (string, optional) — Captured log and debug statements. - `provider_request` (map from string to any, optional) — Raw request sent to provider. - `provider_response` (map from string to any, optional) — Raw response received the provider. - `inputs` (map from string to any, optional) — The inputs passed to the prompt template. - `source` (string, optional) — Identifies where the model was called from. - `metadata` (map from string to any, optional) — Any additional metadata to record. - `source_datapoint_id` (string, optional) — Unique identifier for the Datapoint that this Log is derived from. This can be used by Humanloop to associate Logs to Evaluations. If provided, Humanloop will automatically associate this Log to Evaluations that require a Log for this Datapoint-Version pair. - `trace_parent_id` (string, optional) — The ID of the parent Log to nest this Log under in a Trace. - `user` (string, optional) — End-user ID related to the Log. - `environment` (string, optional) — The name of the Environment the Log is associated to. - `save` (boolean, optional, default: true) — Whether the request/response payloads will be stored on Humanloop. - `log_id` (string, optional) — This will identify a Log. If you don't provide a Log ID, Humanloop will generate one for you. ## Response ### 200 Successful Response - `id` (string, required) — String ID of log. - `tool_id` (string, required) — ID of the Tool the log belongs to. - `version_id` (string, required) — ID of the specific version of the Tool. - `session_id` (string, optional) — String ID of session the log belongs to. ## Errors ### 422 Log Tools Log Post Request Unprocessable Entity Error Validation Error - `detail` (list of ValidationError, optional) ## Types ### ToolKernelRequest - `function` (ToolFunction, optional) — Callable function specification of the Tool shown to the model for tool calling. - `source_code` (string, optional) — Code source of the Tool. - `setup_values` (map from string to any, optional) — Values needed to setup the Tool, defined in JSON Schema format: https://json-schema.org/ - `attributes` (map from string to any, optional) — Additional fields to describe the Tool. Helpful to separate Tool versions from each other with details on how they were created or used. ### ValidationError - `loc` (list of ValidationErrorLocItem, required) - `msg` (string, required) - `type` (string, required) ### ToolFunction - `name` (string, required) — Name for the tool referenced by the model. - `description` (string, required) — Description of the tool referenced by the model - `strict` (boolean, optional, default: false) — If true, forces the model to output json data in the structure of the parameters schema. - `parameters` (map from string to any, optional) — Parameters needed to run the Tool, defined in JSON Schema format: https://json-schema.org/ ### ValidationErrorLocItem ## Examples **Request** ```json { "path": "math-tool", "tool": { "function": { "name": "multiply", "description": "Multiply two numbers", "parameters": { "type": "object", "properties": { "a": { "type": "number" }, "b": { "type": "number" } }, "required": [ "a", "b" ] } } }, "output": "35", "inputs": { "a": 5, "b": 7 } } ``` **Response** ```json { "id": "data_abc123", "tool_id": "tl_def456", "version_id": "tv_ghi789", "session_id": "sesh_hw012" } ``` **SDK Code** ```python Tool log import requests url = "https://api.humanloop.com/v5/tools/log" payload = { "path": "math-tool", "tool": { "function": { "name": "multiply", "description": "Multiply two numbers", "parameters": { "type": "object", "properties": { "a": { "type": "number" }, "b": { "type": "number" } }, "required": ["a", "b"] } } }, "output": "35", "inputs": { "a": 5, "b": 7 } } headers = { "X-API-KEY": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```typescript Tool log import { HumanloopClient } from "humanloop"; const client = new HumanloopClient({ apiKey: "YOUR_API_KEY" }); await client.tools.log({ path: "math-tool", tool: { function: { name: "multiply", description: "Multiply two numbers", parameters: { "type": "object", "properties": { "a": { "type": "number" }, "b": { "type": "number" } }, "required": [ "a", "b" ] } } }, inputs: { "a": 5, "b": 7 }, output: "35" }); ``` ```go Tool log package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.humanloop.com/v5/tools/log" payload := strings.NewReader("{\n \"path\": \"math-tool\",\n \"tool\": {\n \"function\": {\n \"name\": \"multiply\",\n \"description\": \"Multiply two numbers\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"a\": {\n \"type\": \"number\"\n },\n \"b\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"a\",\n \"b\"\n ]\n }\n }\n },\n \"output\": \"35\",\n \"inputs\": {\n \"a\": 5,\n \"b\": 7\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-API-KEY", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Tool log require 'uri' require 'net/http' url = URI("https://api.humanloop.com/v5/tools/log") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-API-KEY"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"path\": \"math-tool\",\n \"tool\": {\n \"function\": {\n \"name\": \"multiply\",\n \"description\": \"Multiply two numbers\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"a\": {\n \"type\": \"number\"\n },\n \"b\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"a\",\n \"b\"\n ]\n }\n }\n },\n \"output\": \"35\",\n \"inputs\": {\n \"a\": 5,\n \"b\": 7\n }\n}" response = http.request(request) puts response.read_body ``` ```java Tool log import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.humanloop.com/v5/tools/log") .header("X-API-KEY", "") .header("Content-Type", "application/json") .body("{\n \"path\": \"math-tool\",\n \"tool\": {\n \"function\": {\n \"name\": \"multiply\",\n \"description\": \"Multiply two numbers\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"a\": {\n \"type\": \"number\"\n },\n \"b\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"a\",\n \"b\"\n ]\n }\n }\n },\n \"output\": \"35\",\n \"inputs\": {\n \"a\": 5,\n \"b\": 7\n }\n}") .asString(); ``` ```php Tool log request('POST', 'https://api.humanloop.com/v5/tools/log', [ 'body' => '{ "path": "math-tool", "tool": { "function": { "name": "multiply", "description": "Multiply two numbers", "parameters": { "type": "object", "properties": { "a": { "type": "number" }, "b": { "type": "number" } }, "required": [ "a", "b" ] } } }, "output": "35", "inputs": { "a": 5, "b": 7 } }', 'headers' => [ 'Content-Type' => 'application/json', 'X-API-KEY' => '', ], ]); echo $response->getBody(); ``` ```csharp Tool log using RestSharp; var client = new RestClient("https://api.humanloop.com/v5/tools/log"); var request = new RestRequest(Method.POST); request.AddHeader("X-API-KEY", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"path\": \"math-tool\",\n \"tool\": {\n \"function\": {\n \"name\": \"multiply\",\n \"description\": \"Multiply two numbers\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"a\": {\n \"type\": \"number\"\n },\n \"b\": {\n \"type\": \"number\"\n }\n },\n \"required\": [\n \"a\",\n \"b\"\n ]\n }\n }\n },\n \"output\": \"35\",\n \"inputs\": {\n \"a\": 5,\n \"b\": 7\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Tool log import Foundation let headers = [ "X-API-KEY": "", "Content-Type": "application/json" ] let parameters = [ "path": "math-tool", "tool": ["function": [ "name": "multiply", "description": "Multiply two numbers", "parameters": [ "type": "object", "properties": [ "a": ["type": "number"], "b": ["type": "number"] ], "required": ["a", "b"] ] ]], "output": "35", "inputs": [ "a": 5, "b": 7 ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.humanloop.com/v5/tools/log")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```