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.

NPM Package (Recommended)

Use our CLI tool: npx @helicone/export - No installation required!

Python Example

See how to query requests using our Python SDK.

TypeScript Example

Learn to fetch requests with TypeScript/JavaScript.

Quick Start with NPM

The easiest way to export data is using our CLI tool:

# Export with npx (no installation required)
HELICONE_API_KEY="your-api-key" npx @helicone/export --start-date 2024-01-01 --limit 10000 --include-body

# With property filter
HELICONE_API_KEY="your-api-key" npx @helicone/export --property appname=MyApp --format csv --include-body

# With date range and full bodies
HELICONE_API_KEY="your-api-key" npx @helicone/export --start-date 2024-08-01 --end-date 2024-08-31 --include-body

# Export from EU region
HELICONE_API_KEY="your-eu-api-key" npx @helicone/export --region eu --limit 10000 --include-body

Key Features:

• ✅ Auto-recovery from crashes with checkpoint system
• ✅ Retry logic with exponential backoff
• ✅ Progress tracking with ETA
• ✅ Multiple output formats (JSON, JSONL, CSV)
• ✅ Region support (US and EU)

See the full documentation for more options.

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

Common Mistake: When filtering by custom properties, you MUST wrap them in a request_response_rmt object. Forgetting this wrapper will return empty results {"data":[],"error":null} even when data exists.

// ❌ WRONG - Missing request_response_rmt wrapper
{
  "filter": {
    "properties": {
      "ticket-id": { "equals": "..." }
    }
  }
}

// ✅ CORRECT - Properties wrapped in request_response_rmt
{
  "filter": {
    "request_response_rmt": {
      "properties": {
        "ticket-id": { "equals": "..." }
      }
    }
  }
}

See the Filtering by Properties section below for complete examples.

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": "[email protected]"
        }
      }
    }
  }
}

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

Troubleshooting

Getting Empty Results {"data":[],"error":null}

If you’re getting empty results when you know data exists, check these common issues:

1. Missing request_response_rmt wrapper for properties

❌ WRONG - Properties without wrapper

curl --request POST \
  --url https://api.helicone.ai/v1/request/query-clickhouse \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "filter": {
    "properties": {
      "ticket-id": {
        "equals": "ba9bf8b3-c04f-41ad-9362-37f8feff7e57"
      }
    }
  }
}'

Result: Empty data even though the property exists

✅ CORRECT - Properties with request_response_rmt wrapper

curl --request POST \
  --url https://api.helicone.ai/v1/request/query-clickhouse \
  --header "Content-Type: application/json" \
  --header "authorization: Bearer $HELICONE_API_KEY" \
  --data '{
  "filter": {
    "request_response_rmt": {
      "properties": {
        "ticket-id": {
          "equals": "ba9bf8b3-c04f-41ad-9362-37f8feff7e57"
        }
      }
    }
  }
}'

Result: Returns all requests with that property value

2. Using wrong API endpoint structure

This endpoint (/query-clickhouse) requires request_response_rmt wrapper for ALL filters including properties. If you’re using the legacy /query endpoint, the filter structure is different - see Get Requests (Legacy).

3. Wrong region

Make sure you’re using the correct regional endpoint:

• US: https://api.helicone.ai/v1/request/query-clickhouse
• EU: https://eu.api.helicone.ai/v1/request/query-clickhouse

4. Property name doesn’t match

Property names are case-sensitive. Check your exact property name in the Helicone dashboard.

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