Runs

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.

Endpoint

https://api.lunary.ai/v1/runs

Example usage

curl --get 'https://api.lunary.ai/v1/runs' \
  -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

Parameter	Type	Required	Description
api_key	string	No	API Key for authentication.
app_id	string	Yes	ID of the application.
search	string	No	Search term for filtering runs.
models	array	No	Filter runs by model names.
tags	array	No	Filter runs by tags.
type	array	No	Filter runs by types: 'llm', 'tool', 'chain', 'agent'.
limit	number	No	Maximum number of results to return. Default is 100.
page	number	No	Page number for pagination.
order	string	No	Sort order, either 'asc' or 'desc'.
min_duration	number	No	Minimum duration for filtering runs.
max_duration	number	No	Maximum duration for filtering runs.
start_time	string	Yes	Start time for the time window filter in ISO 8601 format.
end_time	string	Yes	End 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

Field	Type	Description
data	Run[]	An array of run objects.
total	number	Total number of runs matching the query criteria.
page	number	Current page number in the pagination.
limit	number	Number of items per page, as specified in the query.

Run Object

Each object in the data array contains the following fields:

Field	Type	Description
type	string	The type of the run.
name	string	The name of the model used.
createdAt	string	The creation time of the run.
endedAt	string	The ending time of the run.
duration	number	Duration of the run in seconds.
tokens	Token	Object containing details about token usage.
tags	array	Tags associated with the run.
input	string	Input provided for the run.
output	string	Output of the run.
error	string	Error message, if any.
user	User	Object containing user information.
cost	number	Calculated cost of the run.

Tokens Object

Field	Type	Description
completion	number	Number of completion tokens used.
prompt	number	Number of prompt tokens used.
total	number	Total number of tokens used.

User Object

Field	Type	Description
id	string	User ID.
createdAt	string	Creation time of the user.
lastSeen	string	Last seen time of the user.
props	object	Additional 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": "user1@apple.com"
        }
      },
      "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.