The Runs API endpoint allows you to retrieve data about specific runs from your Lunary application.

It supports various filters to narrow down the results according to your needs.

This endpoint supports GET requests and expects query parameters for filtering the results.


Example usage

curl --get '' \
-H "Authorization: Bearer <private_api_key>" \
-d "start_time=2022-01-01T00:00:00Z" \
-d "end_time=2027-01-02T00:00:00Z" \
-d "limit=10" \
-d "page=0" \
-d "order=asc" \
-d "type=llm"

Query Parameters

api_keystringNoAPI Key for authentication.
app_idstringYesID of the application.
searchstringNoSearch term for filtering runs.
modelsarrayNoFilter runs by model names.
tagsarrayNoFilter runs by tags.
typearrayNoFilter runs by types: 'llm', 'tool', 'chain', 'agent'.
limitnumberNoMaximum number of results to return. Default is 100.
pagenumberNoPage number for pagination.
orderstringNoSort order, either 'asc' or 'desc'.
min_durationnumberNoMinimum duration for filtering runs.
max_durationnumberNoMaximum duration for filtering runs.
start_timestringYesStart time for the time window filter in ISO 8601 format.
end_timestringYesEnd time for the time window filter in ISO 8601 format.

Response Format

The response is a JSON object with the following structure:

Main Response Object

dataRun[]An array of run objects.
totalnumberTotal number of runs matching the query criteria.
pagenumberCurrent page number in the pagination.
limitnumberNumber of items per page, as specified in the query.

Run Object

Each object in the data array contains the following fields:

typestringThe type of the run.
namestringThe name of the model used.
createdAtstringThe creation time of the run.
endedAtstringThe ending time of the run.
durationnumberDuration of the run in seconds.
tokensTokenObject containing details about token usage.
tagsarrayTags associated with the run.
inputstringInput provided for the run.
outputstringOutput of the run.
errorstringError message, if any.
userUserObject containing user information.
costnumberCalculated cost of the run.

Tokens Object

completionnumberNumber of completion tokens used.
promptnumberNumber of prompt tokens used.
totalnumberTotal number of tokens used.

User Object

idstringUser ID.
createdAtstringCreation time of the user.
lastSeenstringLast seen time of the user.
propsobjectAdditional properties associated with the user.

Example Response

"data": [
"type": "llm",
"name": "gpt-3.5",
"createdAt": "2022-01-01T12:00:00Z",
"endedAt": "2022-01-01T12:00:03Z",
"duration": 3,
"tokens": {
"completion": 100,
"prompt": 50,
"total": 150
"tags": ["example", "test"],
"input": "What is the capital of France?",
"output": "The capital of France is Paris.",
"error": null,
"user": {
"id": "user123",
"createdAt": "2021-12-01T12:00:00Z",
"lastSeen": "2022-01-01T12:00:00Z",
"props": {
"email": ""
"cost": 0.05
"total": 200,
"page": 1,
"limit": 10

Error Handling

Standard HTTP status codes are used for error handling:

  • 429: Rate limit exceeded.
  • 422: Missing or incorrect parameters.
  • 403: Unauthorized access.
  • 500: Internal server error.

Questions? We're here to help.