---
title: "Record Completion"
method: POST
path: "/api/v2/projects/{project_id}/sessions/{session_id}/completions"
tags: ["Observability"]
---

# Record Completion

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

Log an LLM completion with its prompt, response, and metadata. This is the primary endpoint for observability. [See SDK method.](https://docs.freeplay.ai/freeplay-sdk/recording-completions)

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.

## Path parameters

- `project_id` string, required
- `session_id` string, required

## Request body

- object
  - `messages` union, required
    - union[]
      - union
        - OpenAISystemMessage
          - `content` string, required
          - `role` 'system'
        - OpenAIDeveloperMessage
          - `content` string, required
          - `role` 'developer'
        - OpenAIUserMessage
          - `content` union, required
            - string
            - union[]
              - …
          - `role` 'user'
        - OpenAIAssistantMessage
          - `content` union
            - string
            - union[]
              - …
            - OpenAITextBlock[]
              - …
            - OpenAIRefusalBlock
              - …
          - `name` string, nullable
          - `audio` OpenAIAudio
            - `id` string, required
            - `data` string, nullable
            - `transcript` string, nullable
          - `refusal` string, nullable
          - `tool_calls` OpenAIToolCall[], nullable
            - `id` string, required
            - `function` OpenAIFunction, required
              - …
            - `type` 'function'
          - `role` 'assistant'
        - OpenAIToolMessage
          - `content` union, required
            - string
            - union[]
              - …
          - `tool_call_id` string, required
          - `role` 'tool'
    - AnthropicMessage[]
      - `content` union, required
        - string
        - union[]
          - union
            - AnthropicTextBlock
              - …
            - AnthropicImageBlock
              - …
            - AnthropicFileBlock
              - …
            - AnthropicToolUseBlock
              - …
            - AnthropicToolResultBlock
              - …
      - `role` 'user' | 'assistant', required
    - SimpleProviderMessage[]
      - `role` union, required
        - 'system'
        - 'developer'
        - 'user'
        - 'assistant'
      - `content` string, required
    - VertexMessage[]
      - `parts` union[], required
        - union
          - VertexTextPart
            - `text` string, required
          - VertexInlineDataPart
            - `inlineData` VertexInlineData, required
              - …
          - VertexFunctionCallPart
            - `functionCall` VertexFunctionCall, required
              - …
            - `thoughtSignature` string, nullable
          - VertexFunctionResponsePart
            - `functionResponse` VertexFunctionResponse, required
              - …
      - `role` 'model' | 'user'
    - BedrockConverseMessage[]
      - `role` 'user' | 'assistant', required
      - `content` union[], required
        - union
          - BedrockTextBlock
            - `text` string, required
            - `type` 'text'
          - BedrockJsonBlock
            - `json` union, required
              - …
            - `type` 'json'
          - BedrockImageBlock
            - `image` BedrockImageContent, required
              - …
            - `type` 'image'
          - BedrockDocumentBlock
            - `document` BedrockDocumentContent, required
              - …
            - `type` 'document'
          - BedrockToolUseBlock
            - `toolUse` BedrockToolUseBlockContent, required
              - …
            - `type` 'toolUse'
          - BedrockToolResultBlock
            - `toolResult` BedrockToolResultBlockContent, required
              - …
            - `type` 'toolResult'
    - union[]
      - union
        - union
          - OpenAIResponsesMessageItem
            - `role` 'user' | 'system' | 'developer' | 'assistant', required
            - `content` union, required
              - …
            - `id` string, nullable
            - `status` string, nullable
            - `type` 'message'
          - OpenAIResponsesFunctionCallItem
            - `name` string, required
            - `arguments` string, required
            - `call_id` string, nullable
            - `id` string, nullable
            - `status` string, nullable
            - `type` 'function_call'
          - OpenAIResponsesFunctionCallOutputItem
            - `output` string, required
            - `call_id` string, nullable
            - `id` string, nullable
            - `type` 'function_call_output'
          - OpenAIResponsesReasoningItem
            - `id` string, nullable
            - `summary` JSONValue[], nullable
              - …
            - `type` 'reasoning'
          - OpenAIResponsesBuiltinToolItem
            - `type` string, required
            - `id` string, nullable
            - `status` string, nullable
        - SimpleProviderMessage
          - `role` union, required
            - 'system'
            - 'developer'
            - 'user'
            - 'assistant'
          - `content` string, required
  - `inputs` object, nullable
  - `media_inputs` object, nullable
  - `tool_schema` union
    - OpenaiTool[]
      - `type` 'function', required
      - `function` OpenaiFunction, required
        - `name` string, required
        - `description` string, required
        - `parameters` object, required
    - AnthropicTool[]
      - `name` string, required
      - `description` string, required
      - `input_schema` object, required
    - VertexTool[]
      - `functionDeclarations` union[], required
        - union
          - OpenaiFunction
            - `name` string, required
            - `description` string, required
            - `parameters` object, required
          - VertexFunction
            - `name` string, required
            - `description` string, required
            - `parameters` object, required
    - OpenaiResponsesTool[]
      - `name` string, required
      - `description` string, required
      - `parameters` object, required
      - `type` 'function'
  - `session_info` SessionInfo
    - `custom_metadata` object, nullable
  - `trace_info` TraceInfo
    - `trace_id` string, uuid, required
  - `prompt_info` PromptInfo
    - `prompt_template_version_id` string, uuid, required
    - `environment` string, nullable
  - `call_info` CallInfo
    - `start_time` number, nullable
    - `end_time` number, nullable
    - `model` string, nullable
    - `provider` string, nullable
    - `provider_info` object, nullable
    - `llm_parameters` object, nullable
    - `usage` UsageInfo
      - `prompt_tokens` integer, required
      - `completion_tokens` integer, required
    - `api_style` 'batch' | 'default'
  - `test_run_info` TestRunInfo
    - `test_run_id` string, uuid, required
    - `test_case_id` string, uuid, required
  - `eval_results` object, nullable
  - `response_info` ResponseInfo
    - `function_call_response` FunctionCall
      - `name` string, required
      - `arguments` string, required
  - `completion_id` string, uuid, nullable
  - `parent_id` string, uuid, nullable
  - `output_schema` object, nullable

## Response `201`

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

- object
  - `completion_id` string, uuid, required — The session entry ID

---

[API](https://skmtc.net/freeplay/apis/freeplay-api.md) · [All operations](https://skmtc.net/freeplay/apis/freeplay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/freeplay/freeplay-api/revisions/69c553220183/schema)