Runs

The /runs endpoint allows you to manage Runs.

List Runs

Endpoint :/runs

Method :GET

Requirements: User must have run:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Query Parameters

Parameter	Data Type	Description
limit	number	The maximum number of runs to return.
offset	number	The number of runs to skip.
interaction	string	The ID of the interaction to filter by.
status	string	The status to filter by.
model	string	The model ID to filter by.
environment	string	The environment ID to filter by.
tag	string	The tag to filter by.
parent	string \| false	The parent run ID to filter by. Pass `false` to filter by runs that do not have a parent.
finish_reason	string	Filter by completion reason. Use 'none' for runs without a finish reason.
created_by	string	Filter by the creator of the run.

Example Request

curl --location 'https://api.vertesia.io/api/v1/runs?limit=10&offset=0' \
--request GET \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Example Response

[
    {
        "id": "<RUN_ID>",
        "interaction": {
            "id": "<INTERACTION_ID>",
            "name": "My Interaction"
        },
        "environment": {
            "id": "<ENVIRONMENT_ID>",
            "name": "My Environment"
        },
        "modelId": "<MODEL_ID>",
        "status": "completed",
        "created_at": "2023-04-20T12:00:00.000Z",
        "updated_at": "2023-04-20T12:00:00.000Z",
        "account": {
            "id": "<ACCOUNT_ID>",
            "name": "My Account"
        },
        "project": {
            "id": "<PROJECT_ID>",
            "name": "My Project"
        },
        "tags": [
            "my-tag"
        ],
        "finish_reason": "completed",
        "created_by": "user:123"
    }
]

Retrieve a Run

Endpoint :/runs/<RUN_ID>

Method :GET

Requirements: User must have run:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`<RUN_ID>` (Required)	string	The ID of the Run to retrieve.

Example Request

curl --location 'https://api.vertesia.io/api/v1/runs/<RUN_ID>' \
--request GET \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Example Response

{
    "id": "<RUN_ID>",
    "interaction": {
        "id": "<INTERACTION_ID>",
        "name": "My Interaction"
    },
    "environment": {
        "id": "<ENVIRONMENT_ID>",
        "name": "My Environment"
    },
    "modelId": "<MODEL_ID>",
    "status": "completed",
    "created_at": "2023-04-20T12:00:00.000Z",
    "updated_at": "2023-04-20T12:00:00.000Z",
    "account": {
        "id": "<ACCOUNT_ID>",
        "name": "My Account"
    },
    "project": {
        "id": "<PROJECT_ID>",
        "name": "My Project"
    },
    "tags": [
        "my-tag"
    ],
    "parameters": {
        "my-param": "my-value"
    },
    "result": {
        "my-result": "my-value"
    },
    "result_schema": {
        "type": "object",
        "properties": {
            "my-result": {
                "type": "string"
            }
        },
        "required": [
            "my-result"
        ]
    },
    "prompt": "My prompt",
    "token_use": {
        "prompt": 10,
        "completion": 5
    },
    "execution_time": 0.5,
    "config": {
        "environment": "<ENVIRONMENT_ID>",
        "model": "<MODEL_ID>"
    },
    "source": {
        "type": "api",
        "label": "My API Client",
        "principal_type": "user",
        "principal_id": "<USER_ID>",
        "client_ip": "127.0.0.1"
    }
}

Code Example

Retrieve a Run

curl --location 'https://api.vertesia.io/api/v1/runs/<RUN_ID>' \
--request GET \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Create a Run

Endpoint :/runs

Method :POST

Requirements: User must have run:write permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
x-interaction-tag	string

Input Parameters

Parameter	Data Type	Description
interaction (Required)	`string`	The ID of the Interaction to run.
data	`object`	The input data for the Interaction.
config	`object`	The configuration for the Interaction run.
stream	`boolean`	Whether to stream the results of the run.

Example Request

{
    "interaction": "<INTERACTION_ID>",
    "data": {
        "my-param": "my-value"
    },
    "config": {
        "environment": "<ENVIRONMENT_ID>",
        "model": "<MODEL_ID>"
    },
    "stream": false
}

Example Response

{
    "id": "<RUN_ID>",
    "status": "created"
}

Code Example

Create a Run

curl --location 'https://api.vertesia.io/api/v1/runs' \
--request POST \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'x-interaction-tag: latest' \
--header 'Content-Type: application/json' \
--data-raw '{
    "interaction": "<INTERACTION_ID>",
    "data": {
        "my-param": "my-value"
    },
    "config": {
        "environment": "<ENVIRONMENT_ID>",
        "model": "<MODEL_ID>"
    },
    "stream": false
}'

The /stream endpoint is not a REST endpoint, but rather a Server-Sent Events (SSE) endpoint. This means that the client will receive a stream of events from the server, rather than a single response.

Endpoint :/runs/<RUN_ID>/stream

Method :GET

Requirements: User must have run:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`<RUN_ID>` (Required)	string	The ID of the Run to stream.

Query Parameters

Parameter	Description
access_token	The JWT token to use for authentication.

Example Request

curl --location 'https://api.vertesia.io/api/v1/runs/<RUN_ID>/stream?access_token=<YOUR_JWT_TOKEN>' \
--request GET

Example Response

event: chunk
data: {"my-result": "my-value"}

event: close
data: {"status": "completed"}

Code Example

Stream a Run

curl --location 'https://api.vertesia.io/api/v1/runs/<RUN_ID>/stream?access_token=<YOUR_JWT_TOKEN>' \
--request GET

Endpoint :/runs/facets

Method :POST

Requirements: User must have run:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
Content-Type	application/json

Input Parameters

This endpoint takes a ComputeRunFacetPayload object as the body of the request.

{
  "facets": [
    {
      "name": "environments",
      "field": "environment"
    },
    {
      "name": "interactions",
      "field": "interaction"
    },
    {
      "name": "models",
      "field": "modelId"
    },
    {
      "name": "tags",
      "field": "tags"
    },
    {
      "name": "status",
      "field": "status"
    }
  ],
  "query": {
    "object": "<OBJECT_ID>"
  }
}

Example Request

curl --location 'https://api.vertesia.io/api/v1/runs/facets' \
--request POST \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "facets": [
    {
      "name": "environments",
      "field": "environment"
    },
    {
      "name": "interactions",
      "field": "interaction"
    },
    {
      "name": "models",
      "field": "modelId"
    },
    {
      "name": "tags",
      "field": "tags"
    },
    {
      "name": "status",
      "field": "status"
    }
  ],
  "query": {
    "object": "<OBJECT_ID>"
  }
}'

Example Response

{
    "environments": [
        {
            "_id": "<ENVIRONMENT_ID>",
            "count": 10
        }
    ],
    "interactions": [
        {
            "_id": "<INTERACTION_ID>",
            "count": 5
        }
    ],
    "models": [
        {
            "_id": "<MODEL_ID>",
            "count": 15
        }
    ],
    "tags": [
        {
            "_id": "my-tag",
            "count": 20
        }
    ],
    "status": [
        {
            "_id": "completed",
            "count": 25
        }
    ],
    "total": 30
}

Code Example

Compute Run Facets

curl --location 'https://api.vertesia.io/api/v1/runs/facets' \
--request POST \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "facets": [
    {
      "name": "environments",
      "field": "environment"
    },
    {
      "name": "interactions",
      "field": "interaction"
    },
    {
      "name": "models",
      "field": "modelId"
    },
    {
      "name": "tags",
      "field": "tags"
    },
    {
      "name": "status",
      "field": "status"
    }
  ],
  "query": {
    "object": "<OBJECT_ID>"
  }
}'

Search Runs

Endpoint :/runs/search

Method :POST

Requirements: User must have run:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
Content-Type	application/json

Input Parameters

This endpoint takes a RunSearchPayload object as the body of the request.

{
  "limit": 10,
  "offset": 0,
  "query": {
    "name": "My Run",
    "status": "completed",
    "interaction": "<INTERACTION_ID>",
    "environment": "<ENVIRONMENT_ID>",
    "model": "<MODEL_ID>",
    "tags": [
      "my-tag"
    ],
    "query": "my search query",
    "parent": [
      "<PARENT_RUN_ID>"
    ],
    "object": "<OBJECT_ID>",
    "start": "2023-04-20T12:00:00.000Z",
    "end": "2023-04-21T12:00:00.000Z"
  }
}

Example Request

curl --location 'https://api.vertesia.io/api/v1/runs/search' \
--request POST \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "limit": 10,
  "offset": 0,
  "query": {
    "name": "My Run",
    "status": "completed",
    "interaction": "<INTERACTION_ID>",
    "environment": "<ENVIRONMENT_ID>",
    "model": "<MODEL_ID>",
    "tags": [
      "my-tag"
    ],
    "query": "my search query",
    "parent": [
      "<PARENT_RUN_ID>"
    ],
    "object": "<OBJECT_ID>",
    "start": "2023-04-20T12:00:00.000Z",
    "end": "2023-04-21T12:00:00.000Z"
  }
}'

Example Response

[
    {
        "id": "<RUN_ID>",
        "interaction": {
            "id": "<INTERACTION_ID>",
            "name": "My Interaction"
        },
        "environment": {
            "id": "<ENVIRONMENT_ID>",
            "name": "My Environment"
        },
        "modelId": "<MODEL_ID>",
        "status": "completed",
        "created_at": "2023-04-20T12:00:00.000Z",
        "updated_at": "2023-04-20T12:00:00.000Z",
        "account": {
            "id": "<ACCOUNT_ID>",
            "name": "My Account"
        },
        "project": {
            "id": "<PROJECT_ID>",
            "name": "My Project"
        },
        "tags": [
            "my-tag"
        ]
    }
]

Code Example

Search Runs

curl --location 'https://api.vertesia.io/api/v1/runs/search' \
--request POST \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "limit": 10,
  "offset": 0,
  "query": {
    "name": "My Run",
    "status": "completed",
    "interaction": "<INTERACTION_ID>",
    "environment": "<ENVIRONMENT_ID>",
    "model": "<MODEL_ID>",
    "tags": [
      "my-tag"
    ],
    "query": "my search query",
    "parent": [
      "<PARENT_RUN_ID>"
    ],
    "object": "<OBJECT_ID>",
    "start": "2023-04-20T12:00:00.000Z",
    "end": "2023-04-21T12:00:00.000Z"
  }
}'

Find Runs

Endpoint :/runs/find

Method :POST

Requirements: User must have run:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
Content-Type	application/json

Input Parameters

Parameter	Data Type	Description
query	object	The MongoDB query to use for finding runs.
limit	number	The maximum number of runs to return.
select	string	A space-separated list of fields to include in the results.

Example Request

{
    "query": {
        "interaction": "<INTERACTION_ID>",
        "status": "completed"
    },
    "limit": 10,
    "select": "id status created_at"
}

Example Response

[
    {
        "id": "<RUN_ID>",
        "status": "completed",
        "created_at": "2023-04-20T12:00:00.000Z"
    }
]

Code Example

Find Runs

curl --location 'https://api.vertesia.io/api/v1/runs/find' \
--request POST \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "query": {
        "interaction": "<INTERACTION_ID>",
        "status": "completed"
    },
    "limit": 10,
    "select": "id status created_at"
}'

Endpoint :/runs/filter-options/<FIELD>

Method :GET

Requirements: User must have run:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`<FIELD>` (Required)	string	The name of the field to get filter options for.

Query Parameters

Parameter	Data Type	Description
interaction	string	The ID of the interaction to filter by.
status	string	The status to filter by.
model	string	The model ID to filter by.
environment	string	The environment ID to filter by.
tag	string	The tag to filter by.
parent	string \| false	The parent run ID to filter by. Pass `false` to filter by runs that do not have a parent.

Example Request

curl --location 'https://api.vertesia.io/api/v1/runs/filter-options/environment' \
--request GET \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Example Response

[
    {
        "id": "<ENVIRONMENT_ID>",
        "name": "My Environment",
        "count": 10
    }
]

Code Example

Get Run Filter Options

curl --location 'https://api.vertesia.io/api/v1/runs/filter-options/environment' \
--request GET \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'