Record Completion

Log an LLM completion with its prompt, response, and metadata. This is the primary endpoint for observability. See SDK method.

Sessions are created implicitly—just generate a session_id client-side (UUID v4). Optionally provide your own completion_id too to avoid waiting for Freeplay’s response.

POST /api/v2/projects/{project_id}/sessions/{session_id}/completions

Record Completion

cURL

curl --request POST \
  --url https://api.example.com/api/v2/projects/{project_id}/sessions/{session_id}/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "messages": [
    {
      "content": "<string>",
      "role": "system"
    }
  ],
  "inputs": null,
  "media_inputs": null,
  "tool_schema": [
    {
      "type": "<string>",
      "function": {
        "name": "<string>",
        "description": "<string>",
        "parameters": {}
      }
    }
  ],
  "session_info": {
    "custom_metadata": null
  },
  "trace_info": {
    "trace_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "prompt_info": {
    "prompt_template_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "environment": null
  },
  "call_info": {
    "start_time": null,
    "end_time": null,
    "model": null,
    "provider": null,
    "provider_info": null,
    "llm_parameters": null,
    "usage": {
      "prompt_tokens": 123,
      "completion_tokens": 123
    }
  },
  "test_run_info": {
    "test_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "test_case_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "eval_results": null,
  "response_info": {
    "function_call_response": {
      "name": "<string>",
      "arguments": "<string>"
    }
  },
  "completion_id": null,
  "parent_id": null,
  "output_schema": null
}
'

201

{
  "completion_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

project_id · string · required

session_id · string · required

Body

application/json

messages · (OpenAISystemMessage · object | OpenAIDeveloperMessage · object | OpenAIUserMessage · object | OpenAIAssistantMessage · object | OpenAIToolMessage · object)[] AnthropicMessage · object[] SimpleProviderMessage · object[] VertexMessage · object[] BedrockConverseMessage · object[] (OpenAIResponsesMessageItem · object | OpenAIResponsesFunctionCallItem · object | OpenAIResponsesFunctionCallOutputItem · object | OpenAIResponsesReasoningItem · object | OpenAIResponsesBuiltinToolItem · object | SimpleProviderMessage · object)[] · required

OpenAISystemMessage

OpenAIDeveloperMessage

OpenAIUserMessage

OpenAIAssistantMessage

OpenAIToolMessage

Show child attributes

inputs · Inputs · object | null

Show child attributes

media_inputs · Media Inputs · object | null

Show child attributes

tool_schema · OpenaiTool · object

OpenaiTool · object[]

AnthropicTool · object[]

VertexTool · object[]

OpenaiResponsesTool · object[]

Show child attributes

session_info · SessionInfo · object | null

Show child attributes

trace_info · TraceInfo · object | null

Show child attributes

prompt_info · PromptInfo · object | null

Show child attributes

call_info · CallInfo · object | null

Show child attributes

test_run_info · TestRunInfo · object | null

Show child attributes

eval_results · Eval Results · object | null

Show child attributes

response_info · ResponseInfo · object | null

Show child attributes

completion_id · string<uuid> | null

parent_id · string<uuid> | null

output_schema · Output Schema · object | null

Response

201 - application/json

RecordCompletionInfo(completion_id: uuid.UUID = FieldInfo(annotation=NoneType, required=True, description='The session entry ID'))

completion_id · string<uuid> · required

The session entry ID