Skip to main content
POST
/
v1
/
request
/
query
cURL
curl --request POST \
  --url https://api.helicone.ai/v1/request/query \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filter": {
    "request_response_rmt": {
      "country_code": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "latency": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "cost": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "provider": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "time_to_first_token": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "status": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "request_created_at": {
        "equals": "2023-11-07T05:31:56Z",
        "gte": "2023-11-07T05:31:56Z",
        "lte": "2023-11-07T05:31:56Z",
        "lt": "2023-11-07T05:31:56Z",
        "gt": "2023-11-07T05:31:56Z"
      },
      "response_created_at": {
        "equals": "2023-11-07T05:31:56Z",
        "gte": "2023-11-07T05:31:56Z",
        "lte": "2023-11-07T05:31:56Z",
        "lt": "2023-11-07T05:31:56Z",
        "gt": "2023-11-07T05:31:56Z"
      },
      "model": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "user_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "organization_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "node_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "job_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "threat": {
        "equals": true
      },
      "request_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "prompt_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "completion_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "prompt_cache_read_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "prompt_cache_write_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "total_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "target_url": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "property_key": {
        "equals": "<string>"
      },
      "properties": {},
      "search_properties": {},
      "scores": {},
      "scores_column": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "request_body": {
        "contains": "<string>"
      },
      "response_body": {
        "contains": "<string>"
      },
      "cache_enabled": {
        "equals": true
      },
      "cache_reference_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "cached": {
        "equals": true
      },
      "assets": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "helicone-score-feedback": {
        "equals": true
      },
      "prompt_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "prompt_version": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "request_referrer": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "is_passthrough_billing": {
        "equals": true
      }
    },
    "response": {
      "body_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "body_model": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "body_completion": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "status": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "model": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      }
    },
    "request": {
      "prompt": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "created_at": {
        "equals": "<string>",
        "gte": "<string>",
        "lte": "<string>",
        "lt": "<string>",
        "gt": "<string>"
      },
      "user_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "auth_hash": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "org_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "node_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "model": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "modelOverride": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "path": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "country_code": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "prompt_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      }
    },
    "feedback": {
      "id": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "created_at": {
        "equals": "<string>",
        "gte": "<string>",
        "lte": "<string>",
        "lt": "<string>",
        "gt": "<string>"
      },
      "rating": {
        "equals": true
      },
      "response_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      }
    },
    "sessions_request_response_rmt": {
      "session_session_id": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "session_session_name": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      },
      "session_total_cost": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "session_total_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "session_prompt_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "session_completion_tokens": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "session_total_requests": {
        "not-equals": 123,
        "equals": 123,
        "gte": 123,
        "lte": 123,
        "lt": 123,
        "gt": 123
      },
      "session_created_at": {
        "equals": "2023-11-07T05:31:56Z",
        "gte": "2023-11-07T05:31:56Z",
        "lte": "2023-11-07T05:31:56Z",
        "lt": "2023-11-07T05:31:56Z",
        "gt": "2023-11-07T05:31:56Z"
      },
      "session_latest_request_created_at": {
        "equals": "2023-11-07T05:31:56Z",
        "gte": "2023-11-07T05:31:56Z",
        "lte": "2023-11-07T05:31:56Z",
        "lt": "2023-11-07T05:31:56Z",
        "gt": "2023-11-07T05:31:56Z"
      },
      "session_tag": {
        "not-equals": "<string>",
        "equals": "<string>",
        "like": "<string>",
        "ilike": "<string>",
        "contains": "<string>",
        "not-contains": "<string>"
      }
    },
    "properties": {},
    "values": {}
  },
  "offset": 123,
  "limit": 123,
  "sort": {
    "random": true,
    "created_at": "asc",
    "cache_created_at": "asc",
    "latency": "asc",
    "last_active": "asc",
    "total_tokens": "asc",
    "completion_tokens": "asc",
    "prompt_tokens": "asc",
    "user_id": "asc",
    "body_model": "asc",
    "is_cached": "asc",
    "request_prompt": "asc",
    "response_text": "asc",
    "properties": {},
    "values": {},
    "cost": "asc",
    "time_to_first_token": "asc"
  },
  "isCached": true,
  "includeInputs": true,
  "isPartOfExperiment": true,
  "isScored": true
}
'
{
  "data": [
    {
      "response_id": "<string>",
      "response_created_at": "<string>",
      "response_status": 123,
      "response_model": "<string>",
      "request_id": "<string>",
      "request_created_at": "<string>",
      "request_body": "<unknown>",
      "request_path": "<string>",
      "request_user_id": "<string>",
      "request_properties": {},
      "request_model": "<string>",
      "model_override": "<string>",
      "helicone_user": "<string>",
      "provider": "OPENAI",
      "delay_ms": 123,
      "time_to_first_token": 123,
      "total_tokens": 123,
      "prompt_tokens": 123,
      "prompt_cache_write_tokens": 123,
      "prompt_cache_read_tokens": 123,
      "completion_tokens": 123,
      "prompt_audio_tokens": 123,
      "completion_audio_tokens": 123,
      "cost": 123,
      "prompt_id": "<string>",
      "prompt_version": "<string>",
      "llmSchema": {
        "request": {
          "llm_type": "chat",
          "provider": "<string>",
          "model": "<string>",
          "messages": [
            {
              "_type": "functionCall",
              "ending_event_id": "<string>",
              "trigger_event_id": "<string>",
              "start_timestamp": "<string>",
              "annotations": [
                {
                  "title": "<string>",
                  "url": "<string>",
                  "type": "url_citation",
                  "content": "<string>"
                }
              ],
              "reasoning": "<string>",
              "deleted": true,
              "contentArray": "<array>",
              "idx": 123,
              "detail": "<string>",
              "filename": "<string>",
              "file_id": "<string>",
              "file_data": "<string>",
              "type": "input_image",
              "audio_data": "<string>",
              "image_url": "<string>",
              "timestamp": "<string>",
              "tool_call_id": "<string>",
              "tool_calls": [
                {
                  "name": "<string>",
                  "arguments": {},
                  "id": "<string>"
                }
              ],
              "mime_type": "<string>",
              "content": "<string>",
              "name": "<string>",
              "instruction": "<string>",
              "role": "<string>",
              "id": "<string>"
            }
          ],
          "prompt": "<string>",
          "instructions": "<string>",
          "max_tokens": 123,
          "temperature": 123,
          "top_p": 123,
          "seed": 123,
          "stream": true,
          "presence_penalty": 123,
          "frequency_penalty": 123,
          "stop": [
            "<string>"
          ],
          "reasoning_effort": "minimal",
          "verbosity": "low",
          "tools": [
            {
              "name": "<string>",
              "description": "<string>",
              "parameters": {}
            }
          ],
          "parallel_tool_calls": true,
          "tool_choice": {
            "type": "none",
            "name": "<string>"
          },
          "response_format": {
            "type": "<string>",
            "json_schema": "<unknown>"
          },
          "toolDetails": {
            "_type": "tool",
            "toolName": "<string>",
            "input": "<unknown>"
          },
          "vectorDBDetails": {
            "_type": "vector_db",
            "operation": "search",
            "text": "<string>",
            "vector": [
              123
            ],
            "topK": 123,
            "filter": {},
            "databaseName": "<string>"
          },
          "dataDetails": {
            "_type": "data",
            "name": "<string>",
            "meta": {}
          },
          "input": "<string>",
          "n": 123,
          "size": "<string>",
          "quality": "<string>"
        },
        "response": {
          "dataDetailsResponse": {
            "name": "<string>",
            "_type": "data",
            "metadata": {
              "timestamp": "<string>"
            },
            "message": "<string>",
            "status": "<string>"
          },
          "vectorDBDetailsResponse": {
            "_type": "vector_db",
            "metadata": {
              "timestamp": "<string>",
              "destination_parsed": true,
              "destination": "<string>"
            },
            "message": "<string>",
            "status": "<string>",
            "actualSimilarity": 123,
            "similarityThreshold": 123
          },
          "toolDetailsResponse": {
            "toolName": "<string>",
            "_type": "tool",
            "metadata": {
              "timestamp": "<string>"
            },
            "tips": [
              "<string>"
            ],
            "message": "<string>",
            "status": "<string>"
          },
          "error": {
            "heliconeMessage": "<unknown>"
          },
          "model": "<string>",
          "instructions": "<string>",
          "responses": [
            {
              "type": "input_image",
              "role": "user",
              "_type": "functionCall",
              "contentArray": "<array>",
              "detail": "<string>",
              "filename": "<string>",
              "file_id": "<string>",
              "file_data": "<string>",
              "idx": 123,
              "audio_data": "<string>",
              "image_url": "<string>",
              "timestamp": "<string>",
              "tool_call_id": "<string>",
              "tool_calls": [
                {
                  "name": "<string>",
                  "arguments": {},
                  "id": "<string>"
                }
              ],
              "text": "<string>",
              "name": "<string>",
              "id": "<string>"
            }
          ],
          "messages": [
            {
              "_type": "functionCall",
              "ending_event_id": "<string>",
              "trigger_event_id": "<string>",
              "start_timestamp": "<string>",
              "annotations": [
                {
                  "title": "<string>",
                  "url": "<string>",
                  "type": "url_citation",
                  "content": "<string>"
                }
              ],
              "reasoning": "<string>",
              "deleted": true,
              "contentArray": "<array>",
              "idx": 123,
              "detail": "<string>",
              "filename": "<string>",
              "file_id": "<string>",
              "file_data": "<string>",
              "type": "input_image",
              "audio_data": "<string>",
              "image_url": "<string>",
              "timestamp": "<string>",
              "tool_call_id": "<string>",
              "tool_calls": [
                {
                  "name": "<string>",
                  "arguments": {},
                  "id": "<string>"
                }
              ],
              "mime_type": "<string>",
              "content": "<string>",
              "name": "<string>",
              "instruction": "<string>",
              "role": "<string>",
              "id": "<string>"
            }
          ]
        }
      },
      "country_code": "<string>",
      "asset_ids": [
        "<string>"
      ],
      "asset_urls": {},
      "scores": {},
      "properties": {},
      "assets": [
        "<string>"
      ],
      "target_url": "<string>",
      "model": "<string>",
      "cache_reference_id": "<string>",
      "cache_enabled": true,
      "ai_gateway_body_mapping": "<string>",
      "response_body": "<unknown>",
      "feedback_created_at": "<string>",
      "feedback_id": "<string>",
      "feedback_rating": true,
      "signed_body_url": "<string>",
      "costUSD": 123,
      "updated_at": "<string>",
      "request_referrer": "<string>",
      "storage_location": "<string>"
    }
  ],
  "error": null
}
For users in the European Union: Please use eu.api.helicone.ai instead of api.helicone.ai.
This API is optimized for point queries. For bulk queries, use the Get Requests (faster) API.
The following API lets you get all of the requests that would be visible in the request table at helicone.ai/requests.

Premade examples 👇

FilterDescription
Get Request by UserGet all the requests made by a user

Filter

A filter is either a FilterLeaf or a FilterBranch, and can be composed of multiple filters generating an AST of ANDs/ORs. Here is how it is represented in typescript:
export interface FilterBranch {
  left: FilterNode;
  operator: "or" | "and"; // Can add more later
  right: FilterNode;
}

export type FilterNode = FilterLeaf | FilterBranch | "all";
This allows us to build complex filters like this:
{
  "filter": {
    "operator": "and",
    "right": {
      "request": {
        "model": {
          "contains": "gpt-4"
        }
      }
    },
    "left": {
      "request": {
        "user_id": {
          "equals": "[email protected]"
        }
      }
    }
  }
}

Authorizations

Authorization
string
header
required

Bearer token authentication. Format: 'Bearer YOUR_API_KEY'

Body

application/json
filter
required

From T, pick a set of properties whose keys are in the union K

offset
number<double>
limit
number<double>
sort
object
isCached
boolean
includeInputs
boolean
isPartOfExperiment
boolean
isScored
boolean

Response

200 - application/json

Ok

data
object[]
required
error
enum<number> | null
required
Available options: