Runs

Runs represent the execution of an agent on a message. They are created when a message is sent to an agent or triggered manually using the API.

Run object

Attributes

id

String

A unique identifier for the run.

status

Enum

The current status of the run.

agent_id

String

A unique identifier for the agent that is processing this run.

trigger_message_group_id

String

The ID of the message group that triggered the run.

cost

Object

Details about the cost associated with the run.

message_group

Object

The message group created as a result of the run.

errors

Array of Objects

A list of errors that occurred during the run.

attached_items

Array of Objects

A list of items attached to the run.

started_at

Date

The date and time when the run started.

created_at

Date

The date and time when the run was created.

completed_at

Date

The date and time when the run was completed.

{
  "id": "run_Rm4Mnheq2bfEPhBhP7SY",
  "status": "success",
  "agent_id": "agent_Rm4Mnheq2bfEPhBhP7SY",
  "trigger_message_group_id": "mgrp_Rm4Mnheq2bfEPhBhP7SY",
  "cost": {
    "amount": 1,
    "unit": "metorial_credits"
  },
  "message_group": {
    "id": "msg_Rm4Mnheq2bfEPhBhP7SY",
    "status": "completed",
    "type": "assistant_message",
    "created_at": "2025-01-01T00:00:00.000Z",
    "thread_id": "thread_Rm4Mnheq2bfEPhBhP7SY",
    "parent_message_group_id": "mgrp_Rm4Mnheq2bfEPhBhP7SY",
    "metadata": {
      "key": "value"
    },
    "messages": [
      {
        "id": "msg_Rm4Mnheq2bfEPhBhP7SY",
        "status": "active",
        "type": "content",
        "message_group_id": "mgrp_Rm4Mnheq2bfEPhBhP7SY",
        "thread_id": "thread_Rm4Mnheq2bfEPhBhP7SY",
        "actor": {
          "id": "act_Rm4Mnheq2bfEPhBhP7SY",
          "name": "John Doe",
          "type": "user",
          "metadata": {
            "email": "[email protected]",
            "other": "Additional metadata can be included here."
          },
          "created_at": "2025-01-01T00:00:00.000Z",
          "updated_at": "2025-01-01T00:00:00.000Z"
        },
        "content": {
          "id": "cnt_Rm4Mnheq2bfEPhBhP7SY",
          "message_item_id": "msg_Rm4Mnheq2bfEPhBhP7SY",
          "attachments": [
            {
              "id": "att_Rm4Mnheq2bfEPhBhP7SY",
              "type": "file",
              "file_id": "file_Rm4Mnheq2bfEPhBhP7SY",
              "url": "https://example.com/file_Rm4Mnheq2bfEPhBhP7SY",
              "caption": "Example file"
            }
          ],
          "parts": [
            {
              "id": "part_Rm4Mnheq2bfEPhBhP7SY",
              "type": "text",
              "text": "Example text"
            }
          ]
        },
        "error": null,
        "created_at": "2025-01-01T00:00:00.000Z"
      },
      {
        "id": "msg_Rm4Mnheq2bfEPhBhP7SY",
        "status": "active",
        "type": "content",
        "message_group_id": "mgrp_Rm4Mnheq2bfEPhBhP7SY",
        "thread_id": "thread_Rm4Mnheq2bfEPhBhP7SY",
        "actor": {
          "id": "act_Rm4Mnheq2bfEPhBhP7SY",
          "name": "John Doe",
          "type": "user",
          "metadata": {
            "email": "[email protected]",
            "other": "Additional metadata can be included here."
          },
          "created_at": "2025-01-01T00:00:00.000Z",
          "updated_at": "2025-01-01T00:00:00.000Z"
        },
        "content": {
          "id": "cnt_Rm4Mnheq2bfEPhBhP7SY",
          "message_item_id": "msg_Rm4Mnheq2bfEPhBhP7SY",
          "attachments": [
            {
              "id": "att_Rm4Mnheq2bfEPhBhP7SY",
              "type": "file",
              "file_id": "file_Rm4Mnheq2bfEPhBhP7SY",
              "url": "https://example.com/file_Rm4Mnheq2bfEPhBhP7SY",
              "caption": "Example file"
            }
          ],
          "parts": [
            {
              "id": "part_Rm4Mnheq2bfEPhBhP7SY",
              "type": "text",
              "text": "Example text"
            }
          ]
        },
        "error": null,
        "created_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "attached_items": [
      {
        "id": "itm_Rm4Mnheq2bfEPhBhP7SY",
        "actor": {
          "id": "act_Rm4Mnheq2bfEPhBhP7SY",
          "name": "John Doe",
          "type": "user",
          "metadata": {
            "email": "[email protected]",
            "other": "Additional metadata can be included here."
          },
          "created_at": "2025-01-01T00:00:00.000Z",
          "updated_at": "2025-01-01T00:00:00.000Z"
        },
        "key": "example_key",
        "value": {
          "example": "value"
        },
        "created_at": "2025-01-01T00:00:00.000Z"
      }
    ],
    "run": {
      "id": "run_Rm4Mnheq2bfEPhBhP7SY",
      "agent_id": "act_Rm4Mnheq2bfEPhBhP7SY",
      "status": "success",
      "metadata": {
        "key": "value"
      },
      "started_at": "2025-01-01T00:00:00.000Z",
      "created_at": "2025-01-01T00:00:00.000Z",
      "completed_at": "2025-01-01T00:00:00.000Z"
    }
  },
  "errors": [
    {
      "id": "err_Rm4Mnheq2bfEPhBhP7SY",
      "run_id": "run_Rm4Mnheq2bfEPhBhP7SY",
      "code": "ERR001",
      "message": "An error occurred.",
      "metadata": {
        "additional": "Additional metadata."
      },
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  ],
  "attached_items": [
    {
      "id": "itm_Rm4Mnheq2bfEPhBhP7SY",
      "actor": {
        "id": "act_Rm4Mnheq2bfEPhBhP7SY",
        "name": "John Doe",
        "type": "user",
        "metadata": {
          "email": "[email protected]",
          "other": "Additional metadata can be included here."
        },
        "created_at": "2025-01-01T00:00:00.000Z",
        "updated_at": "2025-01-01T00:00:00.000Z"
      },
      "key": "example_key",
      "value": {
        "example": "value"
      },
      "created_at": "2025-01-01T00:00:00.000Z"
    },
    {
      "id": "itm_Rm4Mnheq2bfEPhBhP7SY",
      "actor": {
        "id": "act_Rm4Mnheq2bfEPhBhP7SY",
        "name": "John Doe",
        "type": "user",
        "metadata": {
          "email": "[email protected]",
          "other": "Additional metadata can be included here."
        },
        "created_at": "2025-01-01T00:00:00.000Z",
        "updated_at": "2025-01-01T00:00:00.000Z"
      },
      "key": "example_key",
      "value": {
        "example": "value"
      },
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  ],
  "started_at": "2025-03-14T14:14:46.475Z"
}

List runs

Retrieve a list of all runs.

Query Parameters

id

ObjectOptional

Filter results by run IDs.

created_at

ObjectOptional

Filter results by creation date.

started_at

ObjectOptional

Filter results by start date.

completed_at

ObjectOptional

Filter results by completion date.

status

ObjectOptional

Filter results by run status.

GEThttps://api.metorial.com/runs
curl -X GET https://api.metorial.com/runs \
  -H "Authorization: Bearer metorial_sk_..."

Get run

Retrieve details for a single run by its unique identifier.

URL Parameters

runId

String

The unique identifier for the run.

GEThttps://api.metorial.com/runs/:runId
curl -X GET https://api.metorial.com/runs/run_Rm4Mnheq2bfEPhBhP7SY \
  -H "Authorization: Bearer $$SECRET_TOKEN"

Create run

Create a new run by posting a message to a thread.

Request Body

language

StringOptional

The language in which the run is to be executed.

country

StringOptional

The country context for the run.

timezone

StringOptional

The timezone for the run.

metadata

ObjectOptional

Additional metadata for the run.

agent_id

String

The unique identifier for the agent that will process this run.

content

String

The content of the message to process.

content

Object

Detailed structure of the message content.

raw_inputs

ObjectOptional

Raw input data associated with the run.

POSThttps://api.metorial.com/runs
curl -X POST https://api.metorial.com/runs \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
    "language": "en",
    "country": "US",
    "timezone": "America/New_York",
    "agent_id": "agent_Rm4Mnheq2bfEPhBhP7SY",
    "content": "Hello, world!",
    "raw_inputs": {
      "text": "Hello, world!"
    }
  }'