Run an integration's tool

curl --request POST \
  --url https://api.pomerado.ai/v1/integrations/{id}/tools/{tool_id}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": {},
  "login_id": "login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
  "save_login": true,
  "correct_login": true,
  "redact_at_rest": true
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input: {},
    login_id: 'login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190',
    save_login: true,
    correct_login: true,
    redact_at_rest: true
  })
};

fetch('https://api.pomerado.ai/v1/integrations/{id}/tools/{tool_id}/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.pomerado.ai/v1/integrations/{id}/tools/{tool_id}/runs"

payload = {
    "input": {},
    "login_id": "login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "save_login": True,
    "correct_login": True,
    "redact_at_rest": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "job_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
  "type": "run",
  "status": "queued",
  "tool_id": "<string>",
  "input_request": {
    "id": "req_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "expires_at": "<string>",
    "answer_url": "<string>",
    "message": "<string>",
    "questions": [
      {
        "id": "<string>",
        "prompt": "<string>",
        "type": "choice",
        "options": [
          {
            "id": "<string>",
            "label": "<string>"
          }
        ],
        "allow_other": true,
        "allow_note": true
      }
    ]
  },
  "result": "<unknown>",
  "result_status": "available",
  "result_expires_at": "<string>",
  "write_status": "not_attempted",
  "login_save": {
    "status": "saved",
    "login_id": "<string>",
    "reason": "<string>"
  },
  "error": {
    "error": {
      "code": "<string>",
      "message": "<string>",
      "retryable": true,
      "docs_url": "<string>",
      "details": {}
    }
  },
  "message": "<string>",
  "maintenance": {
    "status": "repairing",
    "result_recovered": true,
    "message": "<string>",
    "deadline_at": "<string>"
  },
  "build": {
    "integration_id": "int_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "stage": "queued",
    "stages": [
      {
        "key": "queued",
        "label": "<string>",
        "status": "done",
        "started_at": "<string>",
        "completed_at": "<string>"
      }
    ],
    "eta": {
      "min_seconds": 123,
      "max_seconds": 123
    },
    "example_result": "<unknown>",
    "existing_tool_id": "<string>"
  },
  "watch_url": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "completed_at": "<string>",
  "tip": "<string>"
}

{
  "id": "job_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
  "type": "run",
  "status": "queued",
  "tool_id": "<string>",
  "input_request": {
    "id": "req_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "expires_at": "<string>",
    "answer_url": "<string>",
    "message": "<string>",
    "questions": [
      {
        "id": "<string>",
        "prompt": "<string>",
        "type": "choice",
        "options": [
          {
            "id": "<string>",
            "label": "<string>"
          }
        ],
        "allow_other": true,
        "allow_note": true
      }
    ]
  },
  "result": "<unknown>",
  "result_status": "available",
  "result_expires_at": "<string>",
  "write_status": "not_attempted",
  "login_save": {
    "status": "saved",
    "login_id": "<string>",
    "reason": "<string>"
  },
  "error": {
    "error": {
      "code": "<string>",
      "message": "<string>",
      "retryable": true,
      "docs_url": "<string>",
      "details": {}
    }
  },
  "message": "<string>",
  "maintenance": {
    "status": "repairing",
    "result_recovered": true,
    "message": "<string>",
    "deadline_at": "<string>"
  },
  "build": {
    "integration_id": "int_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "stage": "queued",
    "stages": [
      {
        "key": "queued",
        "label": "<string>",
        "status": "done",
        "started_at": "<string>",
        "completed_at": "<string>"
      }
    ],
    "eta": {
      "min_seconds": 123,
      "max_seconds": 123
    },
    "example_result": "<unknown>",
    "existing_tool_id": "<string>"
  },
  "watch_url": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "completed_at": "<string>",
  "tip": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

POST

integrations

{id}

tools

{tool_id}

runs

Run an integration's tool

curl --request POST \
  --url https://api.pomerado.ai/v1/integrations/{id}/tools/{tool_id}/runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "input": {},
  "login_id": "login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
  "save_login": true,
  "correct_login": true,
  "redact_at_rest": true
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    input: {},
    login_id: 'login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190',
    save_login: true,
    correct_login: true,
    redact_at_rest: true
  })
};

fetch('https://api.pomerado.ai/v1/integrations/{id}/tools/{tool_id}/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.pomerado.ai/v1/integrations/{id}/tools/{tool_id}/runs"

payload = {
    "input": {},
    "login_id": "login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "save_login": True,
    "correct_login": True,
    "redact_at_rest": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "job_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
  "type": "run",
  "status": "queued",
  "tool_id": "<string>",
  "input_request": {
    "id": "req_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "expires_at": "<string>",
    "answer_url": "<string>",
    "message": "<string>",
    "questions": [
      {
        "id": "<string>",
        "prompt": "<string>",
        "type": "choice",
        "options": [
          {
            "id": "<string>",
            "label": "<string>"
          }
        ],
        "allow_other": true,
        "allow_note": true
      }
    ]
  },
  "result": "<unknown>",
  "result_status": "available",
  "result_expires_at": "<string>",
  "write_status": "not_attempted",
  "login_save": {
    "status": "saved",
    "login_id": "<string>",
    "reason": "<string>"
  },
  "error": {
    "error": {
      "code": "<string>",
      "message": "<string>",
      "retryable": true,
      "docs_url": "<string>",
      "details": {}
    }
  },
  "message": "<string>",
  "maintenance": {
    "status": "repairing",
    "result_recovered": true,
    "message": "<string>",
    "deadline_at": "<string>"
  },
  "build": {
    "integration_id": "int_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "stage": "queued",
    "stages": [
      {
        "key": "queued",
        "label": "<string>",
        "status": "done",
        "started_at": "<string>",
        "completed_at": "<string>"
      }
    ],
    "eta": {
      "min_seconds": 123,
      "max_seconds": 123
    },
    "example_result": "<unknown>",
    "existing_tool_id": "<string>"
  },
  "watch_url": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "completed_at": "<string>",
  "tip": "<string>"
}

{
  "id": "job_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
  "type": "run",
  "status": "queued",
  "tool_id": "<string>",
  "input_request": {
    "id": "req_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "expires_at": "<string>",
    "answer_url": "<string>",
    "message": "<string>",
    "questions": [
      {
        "id": "<string>",
        "prompt": "<string>",
        "type": "choice",
        "options": [
          {
            "id": "<string>",
            "label": "<string>"
          }
        ],
        "allow_other": true,
        "allow_note": true
      }
    ]
  },
  "result": "<unknown>",
  "result_status": "available",
  "result_expires_at": "<string>",
  "write_status": "not_attempted",
  "login_save": {
    "status": "saved",
    "login_id": "<string>",
    "reason": "<string>"
  },
  "error": {
    "error": {
      "code": "<string>",
      "message": "<string>",
      "retryable": true,
      "docs_url": "<string>",
      "details": {}
    }
  },
  "message": "<string>",
  "maintenance": {
    "status": "repairing",
    "result_recovered": true,
    "message": "<string>",
    "deadline_at": "<string>"
  },
  "build": {
    "integration_id": "int_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
    "stage": "queued",
    "stages": [
      {
        "key": "queued",
        "label": "<string>",
        "status": "done",
        "started_at": "<string>",
        "completed_at": "<string>"
      }
    ],
    "eta": {
      "min_seconds": 123,
      "max_seconds": 123
    },
    "example_result": "<unknown>",
    "existing_tool_id": "<string>"
  },
  "watch_url": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "completed_at": "<string>",
  "tip": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "docs_url": "<string>",
    "details": {}
  }
}

Details

It works like POST /v1/runs, with the tool named in the path. An integration key reaches only its own integration’s tools.

Callers: an API key, an integration’s API key, an MCP OAuth token or a Dashboard session.
Permission: runs:create.
Effect: Creates or changes something.
Errors: idempotency_conflict, quota_exceeded, quota_expired, acceptance_unknown, not_found, save_forbidden, account_selection_required, saved_login_conflict, login_identity_conflict, legacy_duplicate_saved_logins, saved_login_unsettled, not_configured, invalid_input, unsupported_login_field, file_too_large, file_type_refused, file_unavailable, file_limit_exceeded, file_fetch_failed, and the errors any request can get.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

Repeat a request safely: the same key and body answer the first request's job again with Idempotent-Replayed: true; the same key with a different body answers idempotency_conflict. 1 to 200 letters, digits, _ or -, such as a UUID

Pattern: ^[A-Za-z0-9_-]{1,200}$

Path Parameters

string

required

an integration ID: int_ and 32 lowercase hex digits

Example:

"int_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190"

tool_id

string

required

A tool ID from GET /v1/tools: tool_ and 32 lowercase hex digits

Body

application/json

input

required

The tool's input, as its input_schema describes; {} when it takes none

The saved login to sign in with, when the site has several

Example:

"login_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190"

A login for this call, used only when the site has no saved login: a username (or email, phone or account number) and password, or mode "code" without a password when the site sends a code. It passes through your client and model provider; without it, the run asks the person on its answer page.

Show child attributes

Save login for later runs (requires login)

two_factor_method

enum<string>

The two-factor method to use when the site offers several; one the tool supports

Available options:

sms,

call,

email,

authenticator,

push

Fix the rejected saved login named by login_id during this run

Available options:

true

redact_at_rest

boolean

Staging and preview only: true seals what this job stores and redacts it once it settles, false keeps it readable, overriding the environment's setting. Production refuses a request that names it with invalid_request.

Response

The job this Idempotency-Key already started, with Idempotent-Replayed: true

string

required

a job ID: job_ and 32 lowercase hex digits

Example:

"job_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190"

type

enum<string>

required

Available options:

run,

build

status

enum<string>

required

Available options:

queued,

running,

needs_input,

succeeded,

failed,

cancelled

tool_id

string | null

required

input_request

object | null

required

Show child attributes

result

any

required

result_status

enum<string> | null

required

Available options:

available,

delivered,

expired

result_expires_at

string | null

required

a string to be decoded into a Date

write_status

enum<string> | null

required

Available options:

not_attempted,

may_have_applied,

applied,

not_applied

Show child attributes

error

object | null

required

Show child attributes

message

string | null

required

maintenance

object | null

required

Show child attributes

build

object | null

required

Show child attributes

watch_url

string

required

created_at

string

required

a string to be decoded into a Date

updated_at

string

required

a string to be decoded into a Date

completed_at

string | null

required

a string to be decoded into a Date

tip

string

Overview

Account

Runs

Builds

Jobs

Tools and integrations

Files

Webhooks

Saved logins

2FA

Login access

Team

API keys

Connected apps

Usage and quota

Billing

Run an integration's tool

Authorizations

Headers

Path Parameters

Body

Response