Log Request

POST /log-request

cURL

success

curl --request POST \
  --url https://api.promptlayer.com/log-request \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "provider": "openai",
  "model": "gpt-4o",
  "api_type": "chat-completions",
  "input": {
    "type": "chat",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Hello!"
          }
        ]
      }
    ]
  },
  "output": {
    "type": "chat",
    "messages": [
      {
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "Hi there! How can I help you?"
          }
        ]
      }
    ]
  },
  "request_start_time": "2024-01-15T10:30:00Z",
  "request_end_time": "2024-01-15T10:30:05Z",
  "tags": [
    "production"
  ],
  "metadata": {
    "session_id": "abc123"
  }
}
'

201

{
  "id": 12345,
  "prompt_version": null,
  "status": "SUCCESS",
  "error_type": null,
  "error_message": null
}

Log a request made outside of PromptLayer’s managed run APIs. Use this endpoint for custom providers, background jobs, or direct LLM client calls that you still want to inspect, search, score, and replay in PromptLayer.

Behavior Notes

• input and output must use Prompt Blueprint format.
• Chat message content must be an array of content blocks, not a plain string.
• Provider-specific settings such as structured outputs, tools, tool choice, thinking, and reasoning should be recorded in the prompt blueprint or parameters payload.
• Use status, error_type, and error_message to log failed or degraded requests.

Related

• Custom Logging
• Prompt Blueprints
• Structured Output Logging

Authorizations

X-API-KEY · string · header · required

Body

application/json

Request body for custom logging. Chat message content must be an array of content blocks, not a plain string.

provider · string · required

model · string · required

input · Completion Template · object · required

Completion Template

Chat Template

Show child attributes

output · Completion Template · object · required

Completion Template

Chat Template

Show child attributes

request_start_time · string<date-time> · required

request_end_time · string<date-time> · required

parameters · Parameters · object

Model parameters including temperature, max_tokens, etc. Can also include structured output configuration via response_format.json_schema. See documentation for structured output examples.

tags · string[]

Maximum string length: 512

metadata · Metadata · object

Custom key-value pairs for tracking additional request information. Keys are limited to 1024 characters.

Show child attributes

prompt_name · string | null

prompt_id · integer | null

The ID of the prompt template used for this request. This is useful for tracking which prompt was used in the request.

prompt_version_number · integer | null

Required range: x > 0

prompt_input_variables · Prompt Input Variables · object

input_tokens · integer · default: 0

Required range: x >= 0

output_tokens · integer · default: 0

Required range: x >= 0

price · number · default: 0

Required range: x >= 0

function_name · string · default: ""

score · integer · default: 0

Required range: 0 <= x <= 100

api_type · string | null

status · enum<string> · default: SUCCESS

Request status.

Value	Description
SUCCESS	Request completed successfully (default)
WARNING	Request succeeded but had issues (e.g., retries, degraded response)
ERROR	Request failed

Available options: SUCCESS, WARNING, ERROR

error_type · enum<string> | null

Categorized error type.

Value	Description	Allowed Statuses
PROVIDER_RATE_LIMIT	Rate limit hit on provider API	WARNING, ERROR
PROVIDER_QUOTA_LIMIT	Account quota or spending limit exceeded	WARNING, ERROR
PROVIDER_PARTIAL_RESPONSE	Provider returned a successful response, but the saved output may be incomplete, filtered, blocked, malformed, or otherwise partial	WARNING
VARIABLE_MISSING_OR_EMPTY	Required template variable was missing or empty	WARNING
PROVIDER_TIMEOUT	Request timed out	ERROR
PROVIDER_AUTH_ERROR	Authentication failed with provider	ERROR
PROVIDER_ERROR	General provider-side error	ERROR
TEMPLATE_RENDER_ERROR	Failed to render prompt template	ERROR
UNKNOWN_ERROR	Uncategorized error	WARNING, ERROR

Available options: PROVIDER_TIMEOUT, PROVIDER_QUOTA_LIMIT, PROVIDER_RATE_LIMIT, PROVIDER_PARTIAL_RESPONSE, PROVIDER_AUTH_ERROR, PROVIDER_ERROR, TEMPLATE_RENDER_ERROR, VARIABLE_MISSING_OR_EMPTY, UNKNOWN_ERROR

error_message · string | null

Detailed error message describing what went wrong. Maximum 1024 characters.

Maximum string length: 1024

Response

201

application/json

Successful Response

id · integer · required

prompt_version · PromptVersion · object · required

Show child attributes

status · enum<string>

Request status indicating success, warning, or error.

Available options: SUCCESS, WARNING, ERROR

error_type · string | null

Categorized error type if status is WARNING or ERROR.

error_message · string | null

Detailed error message if status is WARNING or ERROR.