Get Request

Overview

Retrieve detailed information about a specific request using its unique identifier. This endpoint returns comprehensive data about both the request and response, including metadata, token usage, costs, and custom properties.

Endpoint

method

string

required

GET

url

string

required

/v1/request/

Authentication

Requires API key authentication via the Authorization header:

Authorization: Bearer YOUR_API_KEY

Path Parameters

requestId

string

required

The unique identifier of the request to retrieve

Query Parameters

includeBody

boolean

default:"false"

Whether to include the full request and response bodies in the response.

true - Includes complete request/response payloads
false - Returns metadata only (faster, smaller response)

Response

Returns a single request object with detailed information.

data

object

The request object

Show Request Object Properties

request_id

string

Unique identifier for the request

request_created_at

string

Timestamp when the request was created (ISO 8601 format)

request_body

object

The complete request payload sent to the LLM provider (if includeBody=true)

request_path

string

API endpoint path (e.g., “/v1/chat/completions”)

request_user_id

string

User identifier associated with the request

request_properties

object

Custom properties attached to the request at creation time

request_model

string

Model specified in the original API request

response_id

string

Unique identifier for the response

response_created_at

string

Timestamp when the response was received (ISO 8601 format)

response_body

object

The complete response payload from the LLM provider (if includeBody=true)

response_status

number

HTTP status code of the response (e.g., 200, 400, 500)

response_model

string

Actual model used by the provider (may differ from requested model)

model_override

string

Model override applied via Helicone settings

provider

string

LLM provider name (e.g., “OPENAI”, “ANTHROPIC”, “AZURE”, “GOOGLE”)

model

string

Resolved model identifier

target_url

string

The actual URL the request was sent to

delay_ms

number

Total request latency in milliseconds (from request to response)

time_to_first_token

number

Time to first token in milliseconds (for streaming responses)

total_tokens

number

Total tokens used (prompt + completion)

prompt_tokens

number

Number of tokens in the prompt/input

completion_tokens

number

Number of tokens in the completion/output

prompt_cache_write_tokens

number

Tokens written to prompt cache (for providers that support caching)

prompt_cache_read_tokens

number

Tokens read from prompt cache

reasoning_tokens

number

Reasoning tokens used (for models like o1)

prompt_audio_tokens

number

Audio tokens in the prompt (for multimodal models)

completion_audio_tokens

number

Audio tokens in the completion (for multimodal models)

cost

number

Estimated cost of the request in USD

costUSD

number

Cost in USD (same as cost field)

prompt_id

string

ID of the prompt template used (if applicable)

prompt_version

string

Version of the prompt template used

feedback_id

string

ID of the feedback record (if feedback was provided)

feedback_rating

boolean

User feedback rating (true for positive, false for negative)

feedback_created_at

string

Timestamp when feedback was created

scores

object

Evaluation scores as key-value pairs (e.g., {"accuracy": 0.95})

properties

object

All custom properties associated with the request

asset_ids

array

Array of asset IDs associated with the request (e.g., images, files)

asset_urls

object

Map of asset IDs to their signed URLs

cache_enabled

boolean

Whether caching was enabled for this request

cache_reference_id

string

Reference ID for cached responses

country_code

string

Country code of the request origin (ISO 3166-1 alpha-2)

helicone_user

string

Helicone user identifier

updated_at

string

Last update timestamp for the request record

error

string

Error message if the request failed

Examples

Basic Request

Retrieve a request without body data:

curl -X GET "https://api.helicone.ai/v1/request/req_123abc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Request with Full Body

Retrieve a request including complete request and response bodies:

curl -X GET "https://api.helicone.ai/v1/request/req_123abc?includeBody=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Using in Code

const response = await fetch(
  'https://api.helicone.ai/v1/request/req_123abc?includeBody=true',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const result = await response.json();

if (result.data) {
  console.log('Request Model:', result.data.model);
  console.log('Total Tokens:', result.data.total_tokens);
  console.log('Cost:', result.data.cost);
  console.log('Latency:', result.data.delay_ms, 'ms');
}

Response Example

{
  "data": {
    "request_id": "req_123abc",
    "request_created_at": "2024-01-15T10:30:00.000Z",
    "request_path": "/v1/chat/completions",
    "request_model": "gpt-4",
    "request_user_id": "user_456",
    "request_properties": {
      "environment": "production",
      "version": "1.2.3"
    },
    "request_body": {
      "model": "gpt-4",
      "messages": [
        {
          "role": "user",
          "content": "What is the capital of France?"
        }
      ],
      "temperature": 0.7
    },
    "response_id": "res_789def",
    "response_created_at": "2024-01-15T10:30:02.341Z",
    "response_status": 200,
    "response_model": "gpt-4-0613",
    "response_body": {
      "id": "chatcmpl-123",
      "object": "chat.completion",
      "created": 1705317002,
      "model": "gpt-4-0613",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "The capital of France is Paris."
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 15,
        "completion_tokens": 8,
        "total_tokens": 23
      }
    },
    "provider": "OPENAI",
    "model": "gpt-4-0613",
    "target_url": "https://api.openai.com/v1/chat/completions",
    "delay_ms": 2341,
    "time_to_first_token": 234,
    "total_tokens": 23,
    "prompt_tokens": 15,
    "completion_tokens": 8,
    "cost": 0.00069,
    "costUSD": 0.00069,
    "feedback_rating": true,
    "scores": {
      "accuracy": 0.95
    },
    "properties": {
      "environment": "production",
      "version": "1.2.3"
    },
    "cache_enabled": false,
    "updated_at": "2024-01-15T10:30:02.500Z"
  },
  "error": null
}

Error Responses

Request Not Found

{
  "data": null,
  "error": "Request not found"
}

Unauthorized

{
  "data": null,
  "error": "Unauthorized: Invalid API key"
}

Use Cases

Debug specific requests: Investigate issues with particular API calls
Audit trail: Review the complete history of a request and response
Cost analysis: Check token usage and costs for specific requests
Performance monitoring: Analyze latency and time-to-first-token metrics
Quality assurance: Review requests with feedback or evaluation scores
Compliance: Export specific requests for compliance or auditing purposes

Notes

The includeBody parameter significantly increases response size but is necessary for debugging
Request bodies may contain sensitive data - ensure proper access controls
Asset URLs (if present) are pre-signed and time-limited
The cost field is calculated based on token usage and current provider pricing
Some fields may be null depending on the request type and provider

Gateway

Requests

Sessions

Prompts

Evaluations

Overview

Endpoint

Authentication

Path Parameters

Query Parameters

Response

Examples

Basic Request

Request with Full Body

Using in Code

Response Example

Error Responses

Request Not Found

Unauthorized

Use Cases

Notes

Build docs developers (and LLMs) love

Gateway

Requests

Sessions

Prompts

Evaluations

​Overview

​Endpoint

​Authentication

​Path Parameters

​Query Parameters

​Response

​Examples

​Basic Request

​Request with Full Body

​Using in Code

​Response Example

​Error Responses

​Request Not Found

​Unauthorized

​Use Cases

​Notes

Build docs developers (and LLMs) love

Overview

Endpoint

Authentication

Path Parameters

Query Parameters

Response

Examples

Basic Request

Request with Full Body

Using in Code

Response Example

Error Responses

Request Not Found

Unauthorized

Use Cases

Notes