Runs (all kinds)

9 calls. Every request needs the Authorization header: see the overview.

runs.list

GET /processes

Runs, newest first, as compact summaries. Await it for the first page, or iterate every run: for await (const run of mt.runs.list({ state: "Active" })) { … }.

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Query parameters

Name	Type	Required	Description
ids	string		CSV of process ids (at most 50): only these runs, whatever their type. Combines with every other filter. Unknown ids, and ids of another tenant’s runs, are simply absent from the page.
types	string		CSV of App|Interaction|Capsule|CodePipeline (case-insensitive). Empty means all four.
state	string		active|waiting|terminal (case-insensitive).
statuses	string		CSV of raw, type-specific status names (case-insensitive), e.g. Running,PendingApproval.
definitionId	uuid		Only runs of this interaction, app, capsule or code pipeline (its id).
namespaceId	uuid		Runs of any definition in this namespace.
namespace	string[]		Namespace names — repeatable (namespace=a&namespace=b), and each value may also be a CSV: runs of any definition in any of them, including deleted definitions. Names are exact (case-sensitive) and resolved in your tenant only; a name that matches no namespace there matches nothing — if no name matches, the page is empty. At most 50 distinct names. Combines with namespaceId (AND).
rootProcessId	uuid		Only the runs in this run’s tree: the runs whose rootProcessId is this.
parentProcessId	uuid		Only the runs this run started directly: the runs whose parentProcessId is this.
resumeFromProcessId	uuid		Only the runs restarted from this one (their resumeFromProcessId). Only code pipeline runs are ever restarted as a new run, so with this filter no app, interaction or capsule run matches.
retained	boolean		true: only runs a retention lease keeps (their own lease or one inherited from a retained ancestor); false: only runs without one. Absent: both.
createdAfter	datetime		Inclusive lower bound on creation time.
createdBefore	datetime		Exclusive upper bound on creation time.
cursor	string		The nextCursor of the previous page.
limit	integer		1–200, default 50.

Response: ProcessPage (200)

curlTypeScriptPython

curl -X GET "https://api.maitento.com/processes" \
  -H "Authorization: $MAITENTO_AUTH"

for await (const run of mt.runs.list({ types: ["Interaction"], state: "Active" })) console.log(run.id, run.status);

mt.runs.list(state="Terminal", limit=50)

runs.get

GET /processes/by-id/{id}

One run of any kind, as a summary. Throws NotFoundError when there is none.

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Path parameters

Name	Type	Required	Description
id	uuid	yes

Response: ProcessSummary (200)

curlTypeScriptPython

curl -X GET "https://api.maitento.com/processes/by-id/<id>" \
  -H "Authorization: $MAITENTO_AUTH"

const summary = await mt.runs.get("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9");

mt.runs.get("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f")

runs.summary

GET /processes/summary

The runs dashboard: counts, active runs, failures, throughput and tokens over the last hours (1–168).

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Query parameters

Name	Type	Required	Description
hours	integer
namespaceId	uuid
namespace	string[]

Response: ProcessDashboard (200)

curlTypeScriptPython

curl -X GET "https://api.maitento.com/processes/summary" \
  -H "Authorization: $MAITENTO_AUTH"

const dashboard = await mt.runs.summary({ hours: 24 });

mt.runs.summary(hours=24)

runs.kill

POST /processes/{processType}/{processId}/kill

Kills a run of any kind.

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Path parameters

Name	Type	Required	Description
processType	ProcessType	yes
processId	uuid	yes

Response: no body (204)

curlTypeScriptPython

curl -X POST "https://api.maitento.com/processes/<processType>/<processId>/kill" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.runs.kill("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { type: "Interaction" });

mt.runs.kill("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", type="Interaction")

runs.lane

GET /processes/{processType}/{processId}/lane

Whether a run is waiting for a lane before it starts: since when, why, and how many of your runs are ahead of it.

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Path parameters

Name	Type	Required	Description
processType	ProcessType	yes
processId	uuid	yes

Response: RunLaneWait (200)

curlTypeScriptPython

curl -X GET "https://api.maitento.com/processes/<processType>/<processId>/lane" \
  -H "Authorization: $MAITENTO_AUTH"

const wait = await mt.runs.lane("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { type: "Interaction" });

mt.runs.lane("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", type="Interaction")

runs.release

DELETE /processes/{processType}/{processId}/retention-lease

Releases a run’s retention lease: it is then cleared up like any other.

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Path parameters

Name	Type	Required	Description
processType	ProcessType	yes
processId	uuid	yes

Response: ProcessRetentionStatus (200)

curlTypeScriptPython

curl -X DELETE "https://api.maitento.com/processes/<processType>/<processId>/retention-lease" \
  -H "Authorization: $MAITENTO_AUTH"

await mt.runs.release("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { type: "Interaction" });

mt.runs.release("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", type="Interaction")

runs.retention

GET /processes/{processType}/{processId}/retention-lease

How long a run will be kept, and its retention lease.

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Path parameters

Name	Type	Required	Description
processType	ProcessType	yes
processId	uuid	yes

Response: ProcessRetentionStatus (200)

curlTypeScriptPython

curl -X GET "https://api.maitento.com/processes/<processType>/<processId>/retention-lease" \
  -H "Authorization: $MAITENTO_AUTH"

const retention = await mt.runs.retention("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { type: "Interaction" });

mt.runs.retention("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", type="Interaction")

runs.retain

PUT /processes/{processType}/{processId}/retention-lease

Keeps a run (and the runs under it) until released. Idempotent.

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Path parameters

Name	Type	Required	Description
processType	ProcessType	yes
processId	uuid	yes

Request body: ProcessRetentionLeaseRequest

Field	Type	Required	Description
note	string | null		Optional: why the run is being retained (shown with the lease). Trimmed; empty is the same as none. Ignored when the run already has its own lease — a retain never rewrites an existing lease.

Response: ProcessRetentionStatus (200)

curlTypeScriptPython

curl -X PUT "https://api.maitento.com/processes/<processType>/<processId>/retention-lease" \
  -H "Authorization: $MAITENTO_AUTH" \
  -H "Content-Type: application/json" \
  -d '{"note":"..."}'

await mt.runs.retain("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9", { type: "Interaction", note: "Evidence for ticket 4211" });

mt.runs.retain("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f", type="Interaction", note="Customer escalation")

runs.webUsage

GET /web/usage/by-process/{processId}

The metered web searches and fetches a run made.

Who can call it: Admins and members, with an API key or a portal session. Try it in the API playground.

Path parameters

Name	Type	Required	Description
processId	uuid	yes

Response: WebUsageRecord[] (200)

curlTypeScriptPython

curl -X GET "https://api.maitento.com/web/usage/by-process/<processId>" \
  -H "Authorization: $MAITENTO_AUTH"

const webCalls = await mt.runs.webUsage("e4c2a1b3-9d8f-4e7a-b6c5-d4e3f2a1b0c9");

mt.runs.web_usage("b7e6d5c4-3a2b-4c1d-8e9f-0a1b2c3d4e5f")