Get Requests

Retrieve all requests visible in the request table at Helicone.

For users in the European Union: Please use eu.api.helicone.ai instead of api.helicone.ai.

Python Example

See how to query requests using our Python SDK.

TypeScript Example

Learn to fetch requests with TypeScript/JavaScript.

The following API is the same as the Get Requests API, but it is optimized for speed when querying large amount of data. This endpoint will timeout for point queries and is really slow when querying just a few requests.

The following API lets you get all of the requests that would be visible in the request table at helicone.ai/requests.

Premade examples 👇

Filter	Description
Get Request by User	Get all the requests made by a user

Filter Structure

Important: Filters use an AST (Abstract Syntax Tree) structure where each condition must be a separate leaf node. You cannot combine multiple conditions in a single request_response_rmt object.

A filter is either a FilterLeaf or a FilterBranch, and can be composed of multiple filters generating an AST of ANDs/ORs.

TypeScript Types

export interface FilterBranch {
  left: FilterNode;
  operator: "or" | "and";
  right: FilterNode;
}

export type FilterLeaf = {
  request_response_rmt: {
    [field: string]: {
      [operator: string]: any;
    };
  };
};

export type FilterNode = FilterLeaf | FilterBranch | "all";

Simple Filter (Single Condition)

{
  "filter": {
    "request_response_rmt": {
      "model": {
        "contains": "gpt-4"
      }
    }
  }
}

Complex Filter (Multiple Conditions)

Each condition is a separate leaf, connected with and/or operators:

{
  "filter": {
    "left": {
      "request_response_rmt": {
        "model": {
          "contains": "gpt-4"
        }
      }
    },
    "operator": "and",
    "right": {
      "request_response_rmt": {
        "user_id": {
          "equals": "[e-mail]"
        }
      }
    }
  }
}

Match All Requests (No Filter)

{
  "filter": "all"
}

Filtering by Date Range

Date ranges use inclusive bounds - both gte (greater than or equal) and lte (less than or equal) include the specified timestamps.

Single date filter:

{
  "filter": {
    "request_response_rmt": {
      "request_created_at": {
        "gte": "2024-01-01T00:00:00Z"
      }
    }
  }
}

Date range (start AND end):

Important: Each date condition must be a separate leaf! Don’t put both gte and lte in the same object.

{
  "filter": {
    "left": {
      "request_response_rmt": {
        "request_created_at": {
          "gte": "2024-01-01T00:00:00Z"
        }
      }
    },
    "operator": "and",
    "right": {
      "request_response_rmt": {
        "request_created_at": {
          "lte": "2024-12-31T23:59:59Z"
        }
      }
    }
  }
}

Available date operators:

• gte - Greater than or equal (start date, inclusive)
• lte - Less than or equal (end date, inclusive)
• gt - Greater than (exclusive)
• lt - Less than (exclusive)
• equals - Exact timestamp match

Filtering by Properties

Important: When filtering by custom properties, you must nest the properties filter inside a request_response_rmt object.

Single property:

{
  "filter": {
    "request_response_rmt": {
      "properties": {
        "environment": {
          "equals": "production"
        }
      }
    }
  }
}

Combining property filter with other filters:

{
  "filter": {
    "left": {
      "request_response_rmt": {
        "model": {
          "equals": "gpt-4"
        }
      }
    },
    "operator": "and",
    "right": {
      "request_response_rmt": {
        "properties": {
          "environment": {
            "equals": "production"
          }
        }
      }
    }
  }
}

Complete Example: Date Range + Property Filter

This example shows how to combine a date range with a property filter:

{
  "filter": {
    "left": {
      "left": {
        "request_response_rmt": {
          "request_created_at": {
            "gte": "2024-08-01T00:00:00Z"
          }
        }
      },
      "operator": "and",
      "right": {
        "request_response_rmt": {
          "request_created_at": {
            "lte": "2024-08-31T23:59:59Z"
          }
        }
      }
    },
    "operator": "and",
    "right": {
      "request_response_rmt": {
        "properties": {
          "appname": {
            "equals": "LlamaCoder"
          }
        }
      }
    }
  },
  "limit": 100,
  "offset": 0
}

Available Filter Operators

Different fields support different operators:

Text fields (model, user_id, provider, etc.):

• equals / not-equals
• like / ilike (case-insensitive)
• contains / not-contains

Number fields (status, latency, cost, etc.):

• equals / not-equals
• gte / lte / gt / lt

Timestamp fields (request_created_at, response_created_at):

• equals
• gte / lte / gt / lt

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

Show child attributes

offset · number

limit · number

sort · object

Show child attributes

isCached · boolean

includeInputs · boolean

isPartOfExperiment · boolean

isScored · boolean

Response

200 - application/json

Ok

Option 1

data · object[] · required

Show child attributes

error · enum<number> | null · required