🏠
Toolhouse
DiscordGithubSign upGo to App
  • 🏠Toolhouse
  • Quick start: deploy your first agent
  • Build agents with the th file
  • Test agents before deploying
  • Deploy and run your agents
  • Agent workers
    • Running Agents asynchronously
      • API Reference
    • Schedule autonomous runs
      • API Reference
  • Toolhouse SDK
    • ✨Quick start (Python)
    • ✨Quick start (TypeScript)
    • Using LlamaIndex
    • Using Vercel AI
  • Choose MCP servers for your agent
  • Customize agents for your end users
  • 💬Execution logs
  • Go to app
Powered by GitBook
On this page
  1. Agent workers
  2. Running Agents asynchronously

API Reference

PreviousRunning Agents asynchronouslyNextSchedule autonomous runs

Last updated 1 month ago

The Bearer Token is the TOOLHOUSE_API_KEY. You can find your API key(s) .

here

Get Agent Run

get
Authorizations
Path parameters
run_idstring · uuidRequired
Responses
200
Successful Response
application/json
422
Validation Error
application/json
get
GET /v1/agent-runs/{run_id} HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "chat_id": "123e4567-e89b-12d3-a456-426614174000",
    "schedule_id": "123e4567-e89b-12d3-a456-426614174000",
    "results": [
      {}
    ],
    "status": "queued",
    "created_at": "2025-05-13T00:58:14.811Z",
    "updated_at": "2025-05-13T00:58:14.811Z",
    "bundle": "text",
    "toolhouse_id": "text",
    "vars": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "callback_url": "https://example.com",
    "last_agent_message": "text"
  }
}
  • GETGet All Agent Runs
  • POSTCreate Agent Run
  • GETGet Agent Run
  • PUTPut Agent Run

Get All Agent Runs

get
Authorizations
Responses
200
Successful Response
application/json
get
GET /v1/agent-runs HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
200

Successful Response

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "chat_id": "123e4567-e89b-12d3-a456-426614174000",
      "user_id": "text",
      "schedule_id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "queued",
      "results": [
        {}
      ],
      "created_at": "2025-05-13T00:58:14.811Z",
      "updated_at": "2025-05-13T00:58:14.811Z",
      "bundle": "text",
      "toolhouse_id": "text",
      "vars": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "callback_url": "https://example.com"
    }
  ]
}

Create Agent Run

post
Authorizations
Body
chat_idstring · uuidRequired
schedule_idany ofOptional
string · uuidOptional
or
nullOptional
bundlestringOptionalDefault: default
toolhouse_idstringOptionalDefault: default
varsany ofOptional
or
nullOptional
callback_urlany ofOptional
string · uri · min: 1Optional
or
nullOptional
Responses
200
Successful Response
application/json
Responseany
422
Validation Error
application/json
post
POST /v1/agent-runs HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 220

{
  "chat_id": "123e4567-e89b-12d3-a456-426614174000",
  "schedule_id": "123e4567-e89b-12d3-a456-426614174000",
  "bundle": "text",
  "toolhouse_id": "text",
  "vars": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "callback_url": "https://example.com"
}

No content

Put Agent Run

put
Authorizations
Path parameters
run_idstring · uuidRequired
Body
messagestringRequired
Responses
200
Successful Response
application/json
Responseany
422
Validation Error
application/json
put
PUT /v1/agent-runs/{run_id} HTTP/1.1
Host: 
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "message": "text"
}

No content