> 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 Flow POST https://api.humanloop.com/v5/flows/log Content-Type: application/json Log to a Flow. You can use query parameters `version_id`, or `environment`, to target an existing version of the Flow. Otherwise, the default deployed version will be chosen. Reference: https://humanloop.com/docs/api/flows/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 Flow 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. - `messages` (list of ChatMessage, optional) — List of chat messages that were used as an input to the Flow. - `output_message` (ChatMessage, optional) — The output message returned by this Flow. - `run_id` (string, optional) — Unique identifier for the Run to associate the Log to. - `path` (string, optional) — Path of the Flow, including the name. This locates the Flow 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 Flow. - `start_time` (datetime, optional) — The start time of the Trace. Will be updated if a child Log with an earlier start time is added. - `end_time` (datetime, optional) — The end time of the Trace. Will be updated if a child Log with a later end time is added. - `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. - `log_status` (enum, optional) — Status of the Flow Log. When a Log is updated from `incomplete` to `complete`, no more Logs can be added to it. - Allowed values: `complete`, `incomplete` - `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. - `flow` (FlowKernelRequest, optional) — Flow used to generate the Trace. ## Response ### 200 Successful Response - `id` (string, required) — Unique identifier for the Log. - `flow_id` (string, required) — Unique identifier for the Flow. - `version_id` (string, required) — Unique identifier for the Flow Version. - `log_status` (enum, optional) — Status of the Flow Log. When a Flow Log is marked as `complete`, no more Logs can be added to it. - Allowed values: `complete`, `incomplete` ## Errors ### 422 Log Flows Log Post Request Unprocessable Entity Error Validation Error - `detail` (list of ValidationError, optional) ## Types ### ChatMessage - `role` (enum, required) — Role of the message author. - Allowed values: `user`, `assistant`, `system`, `tool`, `developer` - `content` (ChatMessageContent, optional) — The content of the message. - `name` (string, optional) — Optional name of the message author. - `tool_call_id` (string, optional) — Tool call that this message is responding to. - `tool_calls` (list of ToolCall, optional) — A list of tool calls requested by the assistant. - `thinking` (list of ChatMessageThinkingItem, optional) — Model's chain-of-thought for providing the response. Present on assistant messages if model supports it. ### FlowKernelRequest - `attributes` (map from string to any, required) — A key-value object identifying the Flow Version. ### ValidationError - `loc` (list of ValidationErrorLocItem, required) - `msg` (string, required) - `type` (string, required) ### ChatMessageContent The content of the message. ### ToolCall A tool call to be made. - `id` (string, required) - `type` ("function", required) — The type of tool to call. - `function` (FunctionTool, required) — A function tool to be called by the model where user owns runtime. ### ChatMessageThinkingItem ### ValidationErrorLocItem ### FunctionTool A function tool to be called by the model where user owns runtime. - `name` (string, required) - `arguments` (string, optional) ### AnthropicThinkingContent - `type` ("thinking", required) - `thinking` (string, required) — Model's chain-of-thought for providing the response. - `signature` (string, required) — Cryptographic signature that verifies the thinking block was generated by Anthropic. ### AnthropicRedactedThinkingContent - `type` ("redacted_thinking", required) - `data` (string, required) — Thinking block Anthropic redacted for safety reasons. User is expected to pass the block back to Anthropic ## Examples **Request** ```json { "id": "fl_6o701g4jmcanPVHxdqD0O", "start_time": "2024-07-08T22:40:35", "end_time": "2024-07-08T22:40:39", "output": "The patient is likely experiencing a myocardial infarction. Immediate medical attention is required.", "inputs": { "question": "Patient with a history of diabetes and hypertension presents with chest pain and shortness of breath." }, "log_status": "incomplete", "flow": { "attributes": { "prompt": { "template": "You are a helpful assistant helping with medical anamnesis", "model": "gpt-4o", "temperature": 0.8 }, "tool": { "name": "retrieval_tool_v3", "description": "Retrieval tool for MedQA.", "source_code": "def retrieval_tool(question: str) -> str:\n pass\n" } } } } ``` **Response** ```json { "id": "medqa_experiment_0001", "flow_id": "fl_6o701g4jmcanPVHxdqD0O", "version_id": "flv_7ZNQREaScH0JkhUwtXrLN", "log_status": "incomplete" } ``` **SDK Code** ```python Log flow import requests url = "https://api.humanloop.com/v5/flows/log" payload = { "id": "fl_6o701g4jmcanPVHxdqD0O", "start_time": "2024-07-08T22:40:35", "end_time": "2024-07-08T22:40:39", "output": "The patient is likely experiencing a myocardial infarction. Immediate medical attention is required.", "inputs": { "question": "Patient with a history of diabetes and hypertension presents with chest pain and shortness of breath." }, "log_status": "incomplete", "flow": { "attributes": { "prompt": { "template": "You are a helpful assistant helping with medical anamnesis", "model": "gpt-4o", "temperature": 0.8 }, "tool": { "name": "retrieval_tool_v3", "description": "Retrieval tool for MedQA.", "source_code": "def retrieval_tool(question: str) -> str: pass " } } } } headers = { "X-API-KEY": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```typescript Log flow import { HumanloopClient } from "humanloop"; const client = new HumanloopClient({ apiKey: "YOUR_API_KEY" }); await client.flows.log({ id: "fl_6o701g4jmcanPVHxdqD0O", flow: { attributes: { "prompt": { "template": "You are a helpful assistant helping with medical anamnesis", "model": "gpt-4o", "temperature": 0.8 }, "tool": { "name": "retrieval_tool_v3", "description": "Retrieval tool for MedQA.", "source_code": "def retrieval_tool(question: str) -> str:\n pass\n" } } }, inputs: { "question": "Patient with a history of diabetes and hypertension presents with chest pain and shortness of breath." }, output: "The patient is likely experiencing a myocardial infarction. Immediate medical attention is required.", logStatus: "incomplete", startTime: "2024-07-08T22:40:35", endTime: "2024-07-08T22:40:39" }); ``` ```go Log flow package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.humanloop.com/v5/flows/log" payload := strings.NewReader("{\n \"id\": \"fl_6o701g4jmcanPVHxdqD0O\",\n \"start_time\": \"2024-07-08T22:40:35\",\n \"end_time\": \"2024-07-08T22:40:39\",\n \"output\": \"The patient is likely experiencing a myocardial infarction. Immediate medical attention is required.\",\n \"inputs\": {\n \"question\": \"Patient with a history of diabetes and hypertension presents with chest pain and shortness of breath.\"\n },\n \"log_status\": \"incomplete\",\n \"flow\": {\n \"attributes\": {\n \"prompt\": {\n \"template\": \"You are a helpful assistant helping with medical anamnesis\",\n \"model\": \"gpt-4o\",\n \"temperature\": 0.8\n },\n \"tool\": {\n \"name\": \"retrieval_tool_v3\",\n \"description\": \"Retrieval tool for MedQA.\",\n \"source_code\": \"def retrieval_tool(question: str) -> str:\\n pass\\n\"\n }\n }\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 Log flow require 'uri' require 'net/http' url = URI("https://api.humanloop.com/v5/flows/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 \"id\": \"fl_6o701g4jmcanPVHxdqD0O\",\n \"start_time\": \"2024-07-08T22:40:35\",\n \"end_time\": \"2024-07-08T22:40:39\",\n \"output\": \"The patient is likely experiencing a myocardial infarction. Immediate medical attention is required.\",\n \"inputs\": {\n \"question\": \"Patient with a history of diabetes and hypertension presents with chest pain and shortness of breath.\"\n },\n \"log_status\": \"incomplete\",\n \"flow\": {\n \"attributes\": {\n \"prompt\": {\n \"template\": \"You are a helpful assistant helping with medical anamnesis\",\n \"model\": \"gpt-4o\",\n \"temperature\": 0.8\n },\n \"tool\": {\n \"name\": \"retrieval_tool_v3\",\n \"description\": \"Retrieval tool for MedQA.\",\n \"source_code\": \"def retrieval_tool(question: str) -> str:\\n pass\\n\"\n }\n }\n }\n}" response = http.request(request) puts response.read_body ``` ```java Log flow import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.humanloop.com/v5/flows/log") .header("X-API-KEY", "") .header("Content-Type", "application/json") .body("{\n \"id\": \"fl_6o701g4jmcanPVHxdqD0O\",\n \"start_time\": \"2024-07-08T22:40:35\",\n \"end_time\": \"2024-07-08T22:40:39\",\n \"output\": \"The patient is likely experiencing a myocardial infarction. Immediate medical attention is required.\",\n \"inputs\": {\n \"question\": \"Patient with a history of diabetes and hypertension presents with chest pain and shortness of breath.\"\n },\n \"log_status\": \"incomplete\",\n \"flow\": {\n \"attributes\": {\n \"prompt\": {\n \"template\": \"You are a helpful assistant helping with medical anamnesis\",\n \"model\": \"gpt-4o\",\n \"temperature\": 0.8\n },\n \"tool\": {\n \"name\": \"retrieval_tool_v3\",\n \"description\": \"Retrieval tool for MedQA.\",\n \"source_code\": \"def retrieval_tool(question: str) -> str:\\n pass\\n\"\n }\n }\n }\n}") .asString(); ``` ```php Log flow request('POST', 'https://api.humanloop.com/v5/flows/log', [ 'body' => '{ "id": "fl_6o701g4jmcanPVHxdqD0O", "start_time": "2024-07-08T22:40:35", "end_time": "2024-07-08T22:40:39", "output": "The patient is likely experiencing a myocardial infarction. Immediate medical attention is required.", "inputs": { "question": "Patient with a history of diabetes and hypertension presents with chest pain and shortness of breath." }, "log_status": "incomplete", "flow": { "attributes": { "prompt": { "template": "You are a helpful assistant helping with medical anamnesis", "model": "gpt-4o", "temperature": 0.8 }, "tool": { "name": "retrieval_tool_v3", "description": "Retrieval tool for MedQA.", "source_code": "def retrieval_tool(question: str) -> str:\\n pass\\n" } } } }', 'headers' => [ 'Content-Type' => 'application/json', 'X-API-KEY' => '', ], ]); echo $response->getBody(); ``` ```csharp Log flow using RestSharp; var client = new RestClient("https://api.humanloop.com/v5/flows/log"); var request = new RestRequest(Method.POST); request.AddHeader("X-API-KEY", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"id\": \"fl_6o701g4jmcanPVHxdqD0O\",\n \"start_time\": \"2024-07-08T22:40:35\",\n \"end_time\": \"2024-07-08T22:40:39\",\n \"output\": \"The patient is likely experiencing a myocardial infarction. Immediate medical attention is required.\",\n \"inputs\": {\n \"question\": \"Patient with a history of diabetes and hypertension presents with chest pain and shortness of breath.\"\n },\n \"log_status\": \"incomplete\",\n \"flow\": {\n \"attributes\": {\n \"prompt\": {\n \"template\": \"You are a helpful assistant helping with medical anamnesis\",\n \"model\": \"gpt-4o\",\n \"temperature\": 0.8\n },\n \"tool\": {\n \"name\": \"retrieval_tool_v3\",\n \"description\": \"Retrieval tool for MedQA.\",\n \"source_code\": \"def retrieval_tool(question: str) -> str:\\n pass\\n\"\n }\n }\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Log flow import Foundation let headers = [ "X-API-KEY": "", "Content-Type": "application/json" ] let parameters = [ "id": "fl_6o701g4jmcanPVHxdqD0O", "start_time": "2024-07-08T22:40:35", "end_time": "2024-07-08T22:40:39", "output": "The patient is likely experiencing a myocardial infarction. Immediate medical attention is required.", "inputs": ["question": "Patient with a history of diabetes and hypertension presents with chest pain and shortness of breath."], "log_status": "incomplete", "flow": ["attributes": [ "prompt": [ "template": "You are a helpful assistant helping with medical anamnesis", "model": "gpt-4o", "temperature": 0.8 ], "tool": [ "name": "retrieval_tool_v3", "description": "Retrieval tool for MedQA.", "source_code": "def retrieval_tool(question: str) -> str: pass " ] ]] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.humanloop.com/v5/flows/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() ```