App Runs

The App Runs API allows you to retrieve information about the executions of your Scout apps.

GEThttps://api.scoutos.com/v1/apps/runs

Get App Runs

This route retrieves a list of app runs based on the provided query parameters.

Optional Query Parameters

Name
start_date
Type
string
Description
The start date for the query in the format 'YYYY-MM-DD'. Defaults to '1900-1-1'.
Name
end_date
Type
string
Description
The end date for the query in the format 'YYYY-MM-DD'. Defaults to '3000-1-1'.
Name
limit
Type
integer
Description
The maximum number of records to return. Must be less than or equal to 50. Defaults to 50.
Name
session_id
Type
string
Description
The session ID to filter the app runs by.
Name
cursor
Type
string
Description
The cursor for pagination.
Name
status
Type
string
Description
The status of the app runs to retrieve. Can be 'failed', 'completed', or both (comma-separated). Defaults to 'failed,completed'.
Name
direction
Type
string
Description
The order direction for the results. Can be 'asc' or 'desc'. Defaults to 'desc'.

Response Body

Name
schema_version
Type
string
Description
The version of the response schema.
Name
records
Type
array of objects
Description
An array of app run objects containing the following properties:
- timestamp_end: The end timestamp of the app run.
- timestamp_start: The start timestamp of the app run.
- elapsed_time_ms: The elapsed time of the app run in milliseconds.
- blocks: An array of block objects representing the executed blocks in the app run.
- session_id: The session ID of the app run.
- status: The status of the app run ('completed' or 'failed').
- app_run_id: The unique ID of the app run.
- app_id: The ID of the app.
- app_img_url: The URL of the app's image (if available).
- app_display_name: The display name of the app.
- cost: The total cost of the app run.
Name
pagination
Type
object
Description
Contains pagination information:
- next_cursor: The cursor for the next page of results (if available).
- has_more: Indicates whether there are more records available for pagination.
Name
error
Type
string
Description
An error message if an error occurred during the request (null if no error).

Response Models

class BlockConfig(BaseModel):
    item_id: str
    item_display_name: Optional[str] = None
    value: Any

class BlockOutput(BaseModel):
    value: Any

class Block(BaseModel):
    block_config: List[BlockConfig]
    block_output: BlockOutput
    metadata: Optional[Dict[str, Any]] = {}
    block_id: str
    block_type: str
    block_display_name: Optional[str] = None
    block_schema_verson: SchemaVersion = SchemaVersion.V1_0
    elapsed_time_ms: Optional[int] = None
    cost: Optional[float] = None

class AppRun(BaseModel):
    timestamp_end: datetime
    timestamp_start: datetime
    elapsed_time_ms: Optional[int] = None
    blocks: List[Block]
    session_id: str
    status: AppRunStatus
    app_run_id: str
    app_id: str
    app_img_url: Optional[str] = None
    app_display_name: Optional[str] = None
    cost: Optional[float] = None

class Pagination(BaseModel):
    next_cursor: Optional[int] = None
    has_more: bool

class Response(BaseModel):
    schema_version: SchemaVersion
    records: List[AppRun]
    pagination: Pagination
    error: Optional[str]

Request

GET

https://api.scoutos.com/v1/apps/runs

curl -X GET \
  'https://api.scoutos.com/v1/apps/runs?start_date=2023-01-01&end_date=2023-12-31&limit=10&status=completed' \
  -H 'Authorization: Bearer <your-api-key>'

Response

{
  "schema_version": "1.0",
  "records": [
    {
      "timestamp_end": "2023-06-01T10:30:00Z",
      "timestamp_start": "2023-06-01T10:29:45Z",
      "elapsed_time_ms": 15000,
      "blocks": [
        {
          "block_id": "search_block",
          "block_type": "vector_search",
          "block_config": [
            {
              "item_id": "collection_id",
              "value": "my_collection"
            }
          ],
          "metadata": {
            "tokens": 100,
            "messages": 5
          },
          "block_output": {
            "value": [
              {
                "text": "Example result 1",
                "score": 0.9
              },
              {
                "text": "Example result 2",
                "score": 0.8
              }
            ]
          },
          "elapsed_time_ms": 500,
          "cost": 0.01
        },
        {
          "block_id": "output_block",
          "block_type": "text_generation",
          "block_config": [
            {
              "item_id": "prompt",
              "value": "Generate a summary"
            }
          ],
          "metadata": {
            "tokens": 200
          },
          "block_output": {
            "value": "This is a generated summary."
          },
          "elapsed_time_ms": 1000,
          "cost": 0.02
        }
      ],
      "session_id": "abc123",
      "status": "completed",
      "app_run_id": "run_123",
      "app_id": "app_456",
      "app_img_url": "https://example.com/app_image.png",
      "app_display_name": "My App",
      "cost": 0.03
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  },
  "error": null
}