InteractionProcess

A run of an interaction: what it was started with, where it has got to, the whole conversation and its answer.

Kind: an object, used in responses.

Fields

Every field is present in a response; empty ones are null.

Field	Type	Description
`interaction`	`VersionReference`	The interaction, and the version of it, that this run runs.
`dateStarted`	`datetime \| null`	When the run started (UTC). Null until it does.
`dateEnded`	`datetime \| null`	When the run ended (UTC). Null while it is still going.
`executionTime`	`timespan`	How long the run has spent working, not counting time spent waiting for a person. While the run is `Running`, add the time since `dateRunnerClaimed` for the current stretch.
`inputs`	`NameValuePair[]`	The inputs the run was started with.
`output`	`string \| null`	The run’s answer: text, or JSON matching the interaction’s schema (or `responseJsonSchema`). Null until there is one.
`failureDetails`	`string \| null`	Why the run failed or was stopped, as text. Null when it has not.
`status`	`InteractionProcessStatus`	Where the run has got to: waiting to start, running, waiting (for a person, an approval or its sub-interactions), or ended.
`context`	`InteractionProcessContext`	The run’s conversation: every message, tool call and result, grouped by kind. Sort the items by `sequence` to read them in order.
`dateRunnerPing`	`datetime \| null`	When the worker running the run last reported that it was still working (UTC). Null before a worker picks it up.
`dateRunnerClaimed`	`datetime \| null`	When a worker last picked the run up (UTC): the start of its current stretch of work. A run that resumes after waiting for a person gets a new value, and `executionTime` holds the time worked before it. Null until a worker picks the run up.
`waitingForLaneSinceUtc`	`datetime \| null`	When the run started waiting for a lane, in UTC; null when it isn’t waiting. A waiting run is in status New, and `GET /processes/{type}/{id}/lane` says why it waits. Set by Maitento.
`hostname`	`string \| null`	The name of the worker that last ran the run, for diagnostics. Null until a worker picks it up.
`parentProcessId`	`uuid \| null`	The run that started this one: an app run, or the interaction run whose participant started this sub-interaction. Null when no other run started it.
`parentProcessType`	`ProcessType\| null`	What kind of run `parentProcessId` is. Null exactly when that is null.
`rootProcessId`	`uuid \| null`	The run at the top of the tree this run belongs to: the same for every run in the tree, so you can group them without following parent links. Null when no other run started this one.
`triggeredByAutomatedActionId`	`uuid \| null`	The automation that started this run (on its schedule, from a message, or by hand), or null when something else started it.
`triggeredByAutomatedActionName`	`string \| null`	The automation’s name at the time it started this run. Null exactly when `triggeredByAutomatedActionId` is.
`retentionLeaseActive`	`boolean \| null`	True while a retention lease keeps this run: its own, or one inherited from a retained run that started it. A retained run is never deleted when the tenant’s retention period ends. Null or false: not retained.
`retentionLeaseAppliedAtUtc`	`datetime \| null`	When the lease was taken, in UTC. For an inherited lease, when the ancestor’s lease was taken.
`retentionLeaseAppliedByUserId`	`uuid \| null`	The id of the user who took the lease.
`retentionLeaseAppliedByUserName`	`string \| null`	The name of the user who took the lease, as it was when they took it.
`retentionLeaseNote`	`string \| null`	Why it is retained, as the person who retained it wrote it (optional, at most 500 characters).
`retentionLeaseInheritedFromProcessId`	`uuid \| null`	Null when the lease is this run’s own. Otherwise the id of the ancestor run whose lease keeps this one; releasing that run’s lease releases this one too.
`beforeTimeoutStatus`	`InteractionProcessStatus\| null`	When the run ended because a person did not reply in time: the status it was waiting in. Null otherwise.
`responseJsonSchema`	`string \| null`	A JSON Schema the run’s answer must match in place of the interaction’s own, as given when the run started. Null: the interaction’s schema applies.
`pendingApproval`	`PendingToolCallApproval\| null`	The tool call waiting for a person’s approval, while the run is `PendingApproval`. Null otherwise.
`deferredToolCalls`	`DeferredToolCall[] \| null`	Tool calls the model asked for in the same reply as the one awaiting approval. They run, in order, once that approval is decided. Null when there are none.
`disabledTools`	`string[] \| null`	The names of tools this run’s agents are not given, as listed when the run started.
`webDownloadPartitionId`	`uuid \| null`	The temporary knowledge base (partition) the run’s web fetches are kept in: the one given when the run started, else the namespace’s default, else the tenant’s. Runs it starts use it too. Null: no agent of this run may fetch.
`webAccessOverrides`	`WebAccessOverride[] \| null`	The run’s per-agent overrides of the agents’ web tools, as given when it started.
`looms`	`LoomMapping[]`	Which loom each agent of the run wakes up with, settled when the run started.
`loomGifts`	`LoomStartGift[]`	Threads handed to the run’s agents when it started, which each agent learns the first time it wakes.
`aiModelOverrides`	`AiModelOverride[]`	The agents of this run that use a different model from the one their definition names.
`durationAutoTermination`	`timespan \| null`	The longest this run may take: the limit given when it started (or by the run that started it), else the interaction’s own. The run stops with an error when it is reached; time spent waiting for a person does not count. Null: no limit.
`durationWarningToAi`	`timespan \| null`	How long into the run the agents are told that time is running short: the value given when it started, else the interaction’s own. Null: they are not told.
`tokenUsage`	`InteractionProcessTokenUsage[]`	The tokens the run’s model calls used: one record per turn, or more when a turn moved to another key or model. A turn’s record is updated as the turn goes, and is complete once its `finished` is true.
`routingDecisions`	`InteractionRoutingDecision[]`	For participants whose agent is a router: which agent took each turn, and why, oldest first.
`managedDispatch`	`InteractionProcessManagedDispatch\| null`	In a managed interaction: a dispatch held up by a person’s approval of a tool call the dispatched agent made. It is finished first when the run resumes. Null otherwise.
`swarm`	`InteractionProcessSwarm\| null`	This run’s place in a tree of sub-interactions: present when its interaction lets participants start them, and on every run one of them started. Null otherwise.
`credentials`	`InteractionProcessCredential[]`	The model provider keys the run was started with (the keys themselves are never returned). Calls use these first, then your tenant’s model keys. Empty when none were given.
`allowMaitentoFallback`	`boolean \| null`	Whether an agent may fall back to Maitento’s own key once your keys for its provider are used up or have failed (and only when your tenant allows it). Null or false: it may not, and the turn fails instead.
`credentialStack`	`CredentialStackSnapshot\| null`	The credential stack the run uses, as it stood when the run started: which stack, its version, where it was resolved from, and its entries and rules. No secrets: keys are read live at each call. When set, every model call uses only this stack. Null: the run uses the credentials it was started with and the tenant’s model keys.
`credentialFailures`	`InteractionProcessCredentialFailure[]`	Keys that failed during the run and were skipped: which, why and when.
`userCreatedById`	`uuid`	The id of the user who created it. A call made with an API key is recorded as the key’s user.
`tenantId`	`uuid`	The id of the tenant it belongs to.
`id`	`uuid`	The unique id. Use it in `by-id` routes and wherever another object refers to this one.
`dateCreated`	`datetime`	When it was created, in UTC.
`dateUpdated`	`datetime`	When it was last changed, in UTC.

Example

{
  "interaction": {
    "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "version": 0
  },
  "dateStarted": "2026-10-26T12:00:00.0000000Z",
  "dateEnded": "2026-10-26T12:00:00.0000000Z",
  "executionTime": "00:05:00",
  "inputs": [
    {
      "name": "...",
      "value": "..."
    }
  ],
  "output": "...",
  "failureDetails": "...",
  "status": "New",
  "context": {
    "agentMessage": [
      {}
    ],
    "agree": [
      {}
    ],
    "directQuestionAnswer": [
      {}
    ],
    "directQuestionAsk": [
      {}
    ],
    "disagree": [
      {}
    ],
    "humanMessage": [
      {}
    ],
    "injectedSystemMessage": [
      {}
    ],
    "noAction": [
      {}
    ],
    "orchestratorMessage": [
      {}
    ],
    "solutionProposal": [
      {}
    ],
    "systemPrompt": [
      {}
    ],
    "toolCall": [
      {}
    ],
    "toolResult": [
      {}
    ],
    "voteProposal": [
      {}
    ],
    "summary": [
      {}
    ]
  },
  "dateRunnerPing": "2026-10-26T12:00:00.0000000Z",
  "dateRunnerClaimed": "2026-10-26T12:00:00.0000000Z",
  "waitingForLaneSinceUtc": "2026-10-26T12:00:00.0000000Z",
  "hostname": "...",
  "parentProcessId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "parentProcessType": "App",
  "rootProcessId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "triggeredByAutomatedActionId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "triggeredByAutomatedActionName": "...",
  "retentionLeaseActive": false,
  "retentionLeaseAppliedAtUtc": "2026-10-26T12:00:00.0000000Z",
  "retentionLeaseAppliedByUserId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "retentionLeaseAppliedByUserName": "...",
  "retentionLeaseNote": "...",
  "retentionLeaseInheritedFromProcessId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "beforeTimeoutStatus": "New",
  "responseJsonSchema": "...",
  "pendingApproval": {
    "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "functionName": "...",
    "argumentsJson": "...",
    "toolCallId": "...",
    "dateRequested": "2026-10-26T12:00:00.0000000Z",
    "status": "Pending",
    "agentId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "agentName": "..."
  },
  "deferredToolCalls": [
    {
      "toolCallId": "...",
      "functionName": "...",
      "argumentsJson": "...",
      "agentId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "agentName": "..."
    }
  ],
  "disabledTools": [
    "..."
  ],
  "webDownloadPartitionId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "webAccessOverrides": [
    {
      "agentName": "...",
      "search": false,
      "fetch": false
    }
  ],
  "looms": [
    {
      "agentName": "...",
      "loom": "..."
    }
  ],
  "loomGifts": [
    {
      "agentName": "...",
      "fromLoomId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "threadIds": [],
      "note": "...",
      "givenBy": "...",
      "origin": {}
    }
  ],
  "aiModelOverrides": [
    {
      "agentName": "...",
      "aiModelId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "customModel": {},
      "purpose": "Agent"
    }
  ],
  "durationAutoTermination": "00:05:00",
  "durationWarningToAi": "00:05:00",
  "tokenUsage": [
    {
      "turnId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "date": "2026-10-26T12:00:00.0000000Z",
      "provider": "...",
      "model": "...",
      "agentName": "...",
      "agentId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "usages": [],
      "finished": false,
      "credentialId": "...",
      "isOwnLicense": false,
      "tier": "..."
    }
  ],
  "routingDecisions": [
    {
      "date": "2026-10-26T12:00:00.0000000Z",
      "participantName": "...",
      "router": {},
      "chosen": {},
      "reason": "...",
      "isFallback": false,
      "depth": 0
    }
  ],
  "managedDispatch": {
    "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "agentName": "...",
    "message": "...",
    "threadId": "...",
    "recordThreadId": "...",
    "mode": "OneTime",
    "dateStarted": "2026-10-26T12:00:00.0000000Z"
  },
  "swarm": {
    "rootId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "depth": 0,
    "limits": {
      "maxDepth": 0,
      "maxConcurrent": 0,
      "maxTotal": 0
    },
    "started": 0,
    "running": 0,
    "children": [
      {}
    ],
    "released": false,
    "await": {
      "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
      "processIds": [],
      "all": false,
      "participantName": "...",
      "threadId": "...",
      "takenBy": {},
      "dateStarted": "2026-10-26T12:00:00.0000000Z"
    }
  },
  "credentials": [
    {
      "provider": "...",
      "baseUrl": "...",
      "modelNameOverrides": {
        "key": "..."
      },
      "credentialId": "...",
      "isOwnLicense": false,
      "priority": 0
    }
  ],
  "allowMaitentoFallback": false,
  "credentialStack": {
    "stackId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
    "stackName": "...",
    "stackVersion": 0,
    "source": "Start",
    "resolvedAtUtc": "2026-10-26T12:00:00.0000000Z",
    "entries": [
      {}
    ],
    "passesToChildren": false
  },
  "credentialFailures": [
    {
      "credentialId": "...",
      "provider": "...",
      "failureReason": "...",
      "detail": "...",
      "dateUtc": "2026-10-26T12:00:00.0000000Z",
      "retryAfterSeconds": 0
    }
  ],
  "userCreatedById": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "tenantId": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "id": "3f2b8c1e-5d4a-4e6b-9c7d-2a1b0c9d8e7f",
  "dateCreated": "2026-10-26T12:00:00.0000000Z",
  "dateUpdated": "2026-10-26T12:00:00.0000000Z"
}

Where it’s used

interactionRuns.get (GET /interactions/processes/by-id/{id})
interactionRuns.list (GET /interactions/processes)
interactions.start (PUT /interactions/processes/by-id/{id}/start)
interactions.start (PUT /namespaces/{namespaceName}/interactions/by-name/{name}/start)