Runs

The /runs endpoint allows you to manage Runs.

List Runs

Endpoint :/runs

Method :GET

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.

Example Request

curl --location 'https://studio-server-production.api.becomposable.com/api/v1/runs?limit=10&offset=0' \
--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"
        ]
    }
]

Code Examples

List Runs

curl --location 'https://studio-server-production.api.becomposable.com/api/v1/runs?limit=10&offset=0' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Retrieve a Run

Endpoint :/runs/<RUN_ID>

Method :GET

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
`<RUN_ID>`	The ID of the Run to retrieve.

Example Request

curl --location 'https://studio-server-production.api.becomposable.com/api/v1/runs/<RUN_ID>' \
--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 Examples

Retrieve a Run

curl --location 'https://studio-server-production.api.becomposable.com/api/v1/runs/<RUN_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Create a Run

Endpoint :/runs

Method :POST

Headers

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

Input Parameters

Parameter	Data Type	Description
interaction	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 Examples

Create a Run

curl --location 'https://studio-server-production.api.becomposable.com/api/v1/runs' \
--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

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
`<RUN_ID>`	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://studio-server-production.api.becomposable.com/api/v1/runs/<RUN_ID>/stream?access_token=<YOUR_JWT_TOKEN>'

Example Response

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

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

Code Examples

Stream a Run

curl --location 'https://studio-server-production.api.becomposable.com/api/v1/runs/<RUN_ID>/stream?access_token=<YOUR_JWT_TOKEN>'

Endpoint :/runs/facets

Method :POST

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://studio-server-production.api.becomposable.com/api/v1/runs/facets' \
--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 Examples

Compute Run Facets

curl --location 'https://studio-server-production.api.becomposable.com/api/v1/runs/facets' \
--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

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://studio-server-production.api.becomposable.com/api/v1/runs/search' \
--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 Examples

Search Runs

curl --location 'https://studio-server-production.api.becomposable.com/api/v1/runs/search' \
--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

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 Examples

Find Runs

curl --location 'https://studio-server-production.api.becomposable.com/api/v1/runs/find' \
--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

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
`<FIELD>`	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://studio-server-production.api.becomposable.com/api/v1/runs/filter-options/environment' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Example Response

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

Code Examples

Get Run Filter Options

curl --location 'https://studio-server-production.api.becomposable.com/api/v1/runs/filter-options/environment' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'