Return an app's stored HTML (pre-injection — exactly what was saved, without the platform SDK or base stylesheet) plus its version, byte size, name, and scope.
The single path for any change to an app's HTML: pass edits for targeted str_replace changes, imageReplacements to replace embedded images from chat attachments without sending base64 through the m...
The pre-publish gate for an app's head version: static structural checks (findings, each carrying its own specific message) plus the most recent live-render diagnostics (live), with ok true w...
Run one of an app's assigned MCP tools server-side, exactly as the rendered app would (as you, the viewing user, with your MCP credentials), and return its real output.
Optional display icon for the app, as a single emoji character (e.g. "📊") chosen to suit what the app does. Omitted leaves the app with the generic app glyph.
labels
object[]
No
Optional key-value labels for organization and categorization.
labels[].key
string
Yes
labels[].value
string
Yes
tools
string[]
No
Upstream MCP tool names to assign to the new app (e.g. from search_tools), callable from its HTML via archestra.tools.call with the viewing user's credentials. Omitted leaves the app with no assigned tools.
project_id
string
No
Link the new app into this project (from list_projects) so it is listed with the project's files. You need access to the project. Omitted creates a standalone app.
Output
Field
Type
Required
Description
id
string
Yes
name
string
Yes
description
string | null
Yes
scope
"personal" | "team" | "org"
Yes
latestVersion
number
Yes
labels
object[]
Yes
Key-value labels for organization/categorization.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
warnings
string[]
No
Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app.
tools
string[]
No
The app's assigned tool names after this call (present when the tools param was given).
status
"ok" | "partial"
No
Absent or "ok" on full success. "partial" means the app was created (see id) but assigning its tools failed — the app exists; assign them with set_app_tools rather than re-scaffolding.
refine_app
Required RBAC permission: update on the app (granted per item)
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id to refine.
questions
object[]
No
Up to 3 clarifying questions to ask the user before consolidating the spec.
questions[].id
string
Yes
Stable key the answer is returned under.
questions[].prompt
string
Yes
The question shown to the user.
questions[].options
string[]
No
When present, the question is single-select over these plain-string option labels, e.g. ["Light", "Dark"] — never {label, value} objects; otherwise it is free-text.
spec
object
No
The consolidated product requirements to persist on the app (features/data/ui/tools — no implementation stack).
spec.summary
string
Yes
One-line summary of what the app is for.
spec.features
string[]
Yes
Concrete capabilities the app should provide.
spec.data
string | null
No
What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.
spec.ui
string | null
No
UI / style direction as a free-form prose string, not a structured object.
spec.tools
string[]
Yes
Full names of the MCP tools the app calls through window.archestra.
Output
Field
Type
Required
Description
id
string
Yes
spec
object
Yes
The persisted spec when one was given, else the base spec seeded for the model.
spec.summary
string
Yes
One-line summary of what the app is for.
spec.features
string[]
Yes
Concrete capabilities the app should provide.
spec.data
string | null
No
What the app reads/persists via the App Data Store — a free-form prose string, not a structured object.
spec.ui
string | null
No
UI / style direction as a free-form prose string, not a structured object.
spec.tools
string[]
Yes
Full names of the MCP tools the app calls through window.archestra.
capability
object
Yes
capability.tools
object[]
Yes
capability.tools[].name
string
Yes
capability.tools[].description
string
Yes
capability.sdkSummary
string
Yes
answers
object
No
The user's answers to the clarifying questions, if any.
persisted
boolean
Yes
Whether a spec was persisted on the app head by this call.
Filter by name. Each whitespace-separated word must appear in the name or description, in any order — so a remembered name matches even when its word order or punctuation differs from how the app was saved.
labels
object[]
No
Filter by labels. AND across keys, OR within the values given for the same key.
labels[].key
string
Yes
labels[].value
string
Yes
limit
integer
No
access
string[]
No
Only return items the caller reaches in one of these ways: mine (created by the caller), shared (shared with the caller or one of their teams), org (shared with the whole organization), others (not shared with the caller; visible only through admin access). Omit for everything the caller can read. Use ["mine"] for "my apps".
shared_with
string[]
No
Only return items whose own permissions grant read to one of these subjects: org (the whole organization), role:, team:, user:, serviceAccount:. Omit for no filtering.
owner_ids
string[]
No
Only return items created by one of these user IDs. Omit for no filtering.
Output
Field
Type
Required
Description
apps
object[]
Yes
apps[].id
string
Yes
apps[].name
string
Yes
apps[].description
string | null
Yes
apps[].scope
"personal" | "team" | "org"
Yes
apps[].latestVersion
number
Yes
apps[].labels
object[]
Yes
Key-value labels for organization/categorization.
apps[].labels[].key
string
Yes
The label key.
apps[].labels[].value
string
Yes
The label value.
apps[].warnings
string[]
No
Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app.
Specific version to read; defaults to the current head.
offset
integer
No
Start of the read window as a 0-based character offset (a JavaScript string index / UTF-16 code unit) into the stored HTML — character-based, not line-based, since minified HTML can be one enormous line. Defaults to 0. An offset past the end returns an empty window, not an error. A window never splits a character in half: its edges shift by one unit when they would.
limit
integer
No
Maximum number of characters to return, starting at offset. Omitted reads to the end of the document; 0 returns no content, just the size metadata.
Output
Field
Type
Required
Description
id
string
Yes
name
string
Yes
scope
"personal" | "team" | "org"
Yes
version
number
Yes
byteSize
number
Yes
UTF-8 byte size of the full stored HTML (never the window's).
totalChars
number
Yes
Total character length of the full stored HTML.
offset
number
Yes
Effective 0-based character offset of the returned window (0 for a full read; clamped to the end when past it).
hasMore
boolean
Yes
True when the document continues past the returned window.
html
string
Yes
The stored HTML, pre-injection (no SDK/base CSS) — the requested character window when offset/limit was passed.
restore_app_version
Required RBAC permission: update on the app (granted per item)
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id.
version
integer
Yes
The historical version to restore.
baseVersion
integer
Yes
The current head version. This prevents overwriting a newer edit that landed after the rollback was requested.
Output
Field
Type
Required
Description
id
string
Yes
name
string
Yes
description
string | null
Yes
scope
"personal" | "team" | "org"
Yes
latestVersion
number
Yes
labels
object[]
Yes
Key-value labels for organization/categorization.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
warnings
string[]
No
Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app.
edit_app
Required RBAC permission: update on the app (granted per item)
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id.
baseVersion
integer
Yes
The version this edit is based on — the one named by read_app or the latest scaffold_app/edit_app result. Always report the version you actually built the edit from. When the head has moved past it (another conversation edited the app), your edit is treated as a delta from that base and merged with the newer changes; if the regions overlap, the call fails with the head's conflicting content to incorporate.
edits
object[]
No
str_replace edits applied in order to the current HTML; the whole edit is atomic (any failure leaves the app unchanged). Pass exactly one edit mode.
edits[].old_str
string
Yes
Exact text to replace; must occur exactly once in the current HTML (add surrounding context to disambiguate).
edits[].new_str
string
Yes
Replacement text (may be empty to delete).
replacementHtml
string
No
The complete new document, replacing the current HTML outright with no old_str matching — use this for a full rewrite instead of reproducing the whole document as an edit. Pass exactly one edit mode.
replacementHtmlSource
object
No
Like replacementHtml, but the document is read server-side from a file you already saved instead of being written out here — use this when the HTML already exists as a file (assembled in the sandbox, or attached to the chat) so its bytes never have to be reproduced as tool arguments. The file must be UTF-8 text and is subject to the same size limit as any other document. Reads whatever the file holds at call time. Pass exactly one edit mode.
replacementHtmlSource.fileId
string
Yes
Id of a saved file whose bytes become the document, as returned by download_file, save_file, or search_files.
imageReplacements
object[]
No
Replace one or more image URLs with the most recently attached image. Pass short surrounding anchors only: the server reads the newest attachment bytes, builds the data URL, and replaces everything between the anchors. Never put attachment ids, filenames, paths, or old/new base64 in edits/tool arguments. The batch is atomic. Pass exactly one edit mode.
imageReplacements[].before_str
string
Yes
Exact short HTML ending with the opening quote immediately before the existing image URL or data URL (for example <img src="). It must occur exactly once; include nearby id/class context when needed to disambiguate.
imageReplacements[].after_str
string
Yes
Exact short HTML starting with the matching closing quote immediately after the existing image URL or data URL (for example " alt="Issue tracker"). The text between before_str and after_str is replaced server-side.
imageReplacements[].source
object
Yes
The most recently attached image in this conversation. Its bytes are read and encoded server-side; never read or base64-encode the attachment yourself.
imageReplacements[].source.type
"chat_attachment"
Yes
Output
Field
Type
Required
Description
id
string
Yes
name
string
Yes
description
string | null
Yes
scope
"personal" | "team" | "org"
Yes
latestVersion
number
Yes
labels
object[]
Yes
Key-value labels for organization/categorization.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
warnings
string[]
No
Soft save-time validation warnings about the html (the save succeeded); fix them via edit_app.
set_app_tools
Required RBAC permission: update on the app (granted per item)
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id whose tools to set.
tools
string[]
Yes
Upstream MCP tool names (e.g. from search_tools) to assign to the app, replacing its current set exactly — pass the full desired list, or [] to clear all.
Output
Field
Type
Required
Description
id
string
Yes
tools
string[]
Yes
The app's assigned tool names after this call.
set_app_labels
Required RBAC permission: update on the app (granted per item)
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id whose labels to set.
labels
object[]
Yes
Key-value labels to assign to the app, replacing its current set exactly — pass the full desired list, or [] to clear all. One value per key; a repeated key keeps the last one.
labels[].key
string
Yes
labels[].value
string
Yes
Output
Field
Type
Required
Description
id
string
Yes
labels
object[]
Yes
The app's labels after this call.
labels[].key
string
Yes
The label key.
labels[].value
string
Yes
The label value.
set_app_lock
Required RBAC permission: update on the app (granted per item)
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id.
locked
boolean
Yes
true locks the app against all modification; false unlocks it (only on the user's direct request).
Diagnostics from the most recent live render of the head version (untrusted iframe output). status no_render_observed means no render of this version has happened yet — live diagnostics are captured only when the app renders for a viewer, so this is the normal state right after authoring and a clean static pass (ok: true) is enough to proceed.
live.status
"no_render_observed" | "clean" | "errors"
Yes
live.version
number
Yes
live.entries
object[]
Yes
live.entries[].type
string
Yes
live.entries[].message
string
Yes
live.renderedAt
string | null
Yes
publish_app
Required RBAC permission: manage-permissions on the app (granted per item)
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id to publish.
scope
"team" | "org"
Yes
Publish to specific teams or to the whole organization. Promotes the app out of personal scope.
teams
string[]
No
Target teams, each a team name or team id — required when scope is team. Pass the team name the user gave (e.g. ["Platform"]); no need to look up ids first.
Output
Field
Type
Required
Description
id
string
Yes
scope
"personal" | "team" | "org"
Yes
runUrl
string
Yes
Standalone page for the published app.
preview_app_tool
Required RBAC permission: update on the app (granted per item)
Input
Parameter
Type
Required
Description
appId
string
Yes
The app id whose assigned tool to run.
toolName
string
Yes
Name of an MCP tool assigned to the app (exactly as archestra.tools.call would receive it).
args
object
No
Arguments to pass to the tool (defaults to {}).
Output
Field
Type
Required
Description
toolName
string
Yes
isError
boolean
Yes
truncated
boolean
Yes
output
string
Yes
The JSON-serialized value archestra.tools.call resolves with for this result, framed as untrusted data (media dataUrls are elided).
Storage partition: "user" (default) is private to the viewing user, "app" is shared by everyone using the app.
Output
Field
Type
Required
Description
value
any
Yes
revision
integer | null
Yes
owner
string | null
Yes
User id owning a shared key, or null if collaborative.
app_data_set
Required RBAC permission: update on the app (granted per item)
Input
Parameter
Type
Required
Description
key
string
Yes
The data store key.
value
any
Yes
Any JSON-serializable value except null (use app_data_delete to clear a key). Pass objects/arrays directly — get returns exactly what was stored, no JSON.stringify needed.
scope
"user" | "app"
No
Storage partition: "user" (default) is private to the viewing user, "app" is shared by everyone using the app.
expectedRevision
integer
No
Optimistic concurrency guard. Omit for last-writer-wins. 0 = create only if the key is absent. A positive value = overwrite only if the key is still at that revision (from a prior get/set); otherwise the write is rejected as a conflict.
claimOwner
boolean
No
Shared-scope only: when creating a NEW key, claim it so only you (or an app admin/author) may later overwrite or delete it. Has no effect on the "user" scope or on an existing key.
Output
Field
Type
Required
Description
key
string
Yes
revision
integer
Yes
owner
string | null
Yes
User id owning a shared key, or null if collaborative.
Read one project's context in a single call: its metadata, its instructions (the instructions.md that steers every chat in the project), the files it owns, and the apps linked into it that you ca...
List the scheduled agent triggers the caller can see: which agent each one runs, its cron expression and timezone, whether it is enabled, and when it last fired.
List a scheduled task's run history, newest first: whether each run was due or manual, how it ended, when it started and completed, its failure text, and the chat conversation holding its transcript.
Read what one scheduled task run did: its messages and every tool call with arguments, result and error, including guardrails rulings, remedy offers and review outcomes returned to the agent.
Additional access requirement: Returns only projects the caller owns or that are shared with them. Oversight of every project (a * grant) does not extend to this tool.
Input
Parameter
Type
Required
Description
query
string
No
Case-insensitive substring matched against the project name and description. Omit to list everything the caller can reach.
access
string[]
No
Only return items the caller reaches in one of these ways: mine (created by the caller), shared (shared with the caller or one of their teams), org (shared with the whole organization), others (not shared with the caller; visible only through admin access). Omit for everything the caller can read. Use ["mine"] for "my projects".
shared_with
string[]
No
Only return items whose own permissions grant read to one of these subjects: org (the whole organization), role:, team:, user:, serviceAccount:. Omit for no filtering.
owner_ids
string[]
No
Only return items created by one of these user IDs. Omit for no filtering.
Output
Field
Type
Required
Description
projects
object[]
Yes
Projects the caller can reach.
projects[].id
string
Yes
The project's id — pass it to get_project.
projects[].name
string
Yes
The project's name.
projects[].description
string | null
Yes
The project's description.
projects[].visibility
"organization" | "team" | "user" | null
Yes
Who the project is shared with; null = owner-only.
Additional access requirement: Readable only for projects the caller owns or that are shared with them. Oversight of every project (a * grant) does not extend to this tool.
Input
Parameter
Type
Required
Description
project_id
string
Yes
Id of the project to read (from list_projects).
Output
Field
Type
Required
Description
id
string
Yes
The project's id — pass it to get_project.
name
string
Yes
The project's name.
description
string | null
Yes
The project's description.
visibility
"organization" | "team" | "user" | null
Yes
Who the project is shared with; null = owner-only.
viewer_role
"owner" | "shared" | "admin"
Yes
The caller's relationship to the project.
owner_name
string | null
Yes
Display name of the owner.
labels
object[]
Yes
Key/value labels assigned to the project.
labels[].key
string
Yes
labels[].value
string
Yes
labels[].keyId
string
No
labels[].valueId
string
No
conversation_count
integer
Yes
How many chats live in the project.
created_at
string
Yes
ISO 8601 creation timestamp.
instructions
string
Yes
The project's instructions markdown; empty when never saved. Truncated when instructions_truncated is true.
instructions_truncated
boolean
Yes
Whether instructions was cut short at the inline limit.
files
object[]
Yes
Files the project owns. Read one with read_file, passing the same project_id and this ref.
files[].id
string
Yes
The file's id.
files[].ref
string
Yes
Stable reference to pass to read_file.
files[].filename
string
Yes
The file's name.
files[].mime_type
string
Yes
The file's MIME type.
files[].size_bytes
integer
Yes
Size in bytes.
apps
object[]
Yes
Apps linked into the project that you can open. Read or edit one with the app tools, passing this id.
Additional access requirement: Requires an acting user. Omitting project_id creates a private project with the task prompt as its instructions. Repeating the same new-project task returns the existing schedule. An existing project must be accessible to the caller.
Input
Parameter
Type
Required
Description
name
string
Yes
Name of the scheduled task.
project_id
string
No
Existing project to schedule in. Omit to create a private project using name and message_template as its instructions.
agent_id
string
No
Agent to run. For a new project, defaults to the current agent; for an existing project, its agent then the organization default.
cron_expression
string
Yes
Cron expression, for example 0 9 * * 1-5.
timezone
string
Yes
IANA timezone, for example America/Toronto.
message_template
string
Yes
Prompt sent to the agent on each run.
enabled
boolean
No
Whether the schedule is enabled. Defaults to true on creation.
Output
Field
Type
Required
Description
id
string
Yes
The trigger's id — pass it to get_schedule_trigger.
name
string
Yes
The trigger's name.
agent_id
string
Yes
Id of the agent the schedule runs.
agent_name
string | null
Yes
Name of that agent.
project_id
string | null
Yes
Project the schedule belongs to, when it is project-scoped.
cron_expression
string
Yes
5-part cron expression driving the schedule.
timezone
string
Yes
IANA timezone the cron expression is read in.
enabled
boolean
Yes
Whether the schedule is currently picked up when due.
last_executed_at
string | null
Yes
ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity.
actor_user_id
string
Yes
The user the scheduled run executes as.
actor_name
string | null
Yes
Display name of that user.
created_at
string
Yes
ISO 8601 creation timestamp.
message_template
string
Yes
The prompt sent to the agent on every run.
created
boolean
Yes
False when an identical new-project request reused an existing schedule.
Additional access requirement: Requires a user token. Only the schedule actor or someone with organization-wide Projects Can update access can perform this action. Project membership alone permits reading. See Granular Access Control.
Input
Parameter
Type
Required
Description
name
string
No
Name of the scheduled task.
project_id
string
No
Project containing the scheduled task.
agent_id
string
No
Agent to run. Defaults to the project's agent, then the organization default.
cron_expression
string
No
Cron expression, for example 0 9 * * 1-5.
timezone
string
No
IANA timezone, for example America/Toronto.
message_template
string
No
Prompt sent to the agent on each run.
enabled
boolean
No
Whether the schedule is enabled. Defaults to true on creation.
schedule_trigger_id
string
Yes
Output
Field
Type
Required
Description
id
string
Yes
The trigger's id — pass it to get_schedule_trigger.
name
string
Yes
The trigger's name.
agent_id
string
Yes
Id of the agent the schedule runs.
agent_name
string | null
Yes
Name of that agent.
project_id
string | null
Yes
Project the schedule belongs to, when it is project-scoped.
cron_expression
string
Yes
5-part cron expression driving the schedule.
timezone
string
Yes
IANA timezone the cron expression is read in.
enabled
boolean
Yes
Whether the schedule is currently picked up when due.
last_executed_at
string | null
Yes
ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity.
Additional access requirement: Requires a user token. Only the schedule actor or someone with organization-wide Projects Full access access can perform this action. Project membership alone permits reading. See Granular Access Control.
Additional access requirement: Requires a user token. The caller must be the schedule actor, a project member, or someone with organization-wide Projects Can read access.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule to read.
Output
Field
Type
Required
Description
id
string
Yes
The trigger's id — pass it to get_schedule_trigger.
name
string
Yes
The trigger's name.
agent_id
string
Yes
Id of the agent the schedule runs.
agent_name
string | null
Yes
Name of that agent.
project_id
string | null
Yes
Project the schedule belongs to, when it is project-scoped.
cron_expression
string
Yes
5-part cron expression driving the schedule.
timezone
string
Yes
IANA timezone the cron expression is read in.
enabled
boolean
Yes
Whether the schedule is currently picked up when due.
last_executed_at
string | null
Yes
ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity.
Additional access requirement: Requires a user token. The caller must be the schedule actor, a project member, or someone with organization-wide Projects Can read access.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule whose runs to list.
status
"running" | "success" | "failed" | "cancelled"
No
Only runs in this state.
limit
integer
No
How many rows to return, newest first (1-100, default 25).
cursor
string
No
Pass pagination.nextCursor from the previous response to read the next page. Keep the same filters; omit for the newest page.
Output
Field
Type
Required
Description
pagination
object
Yes
pagination.limit
integer
Yes
pagination.nextCursor
string | null
Yes
pagination.hasNext
boolean
Yes
runs
object[]
Yes
Matching runs, newest first.
runs[].blocked_by
object | null
Yes
Why this tick was skipped, including the blocking run and its frozen deadline.
runs[].blocked_by.phase
"starting" | "running" | "stopping"
Yes
runs[].blocked_by.runId
string | null
Yes
runs[].blocked_by.runtimeTaskId
string | null
Yes
runs[].blocked_by.startedAt
string
Yes
runs[].blocked_by.elapsedSeconds
integer
Yes
runs[].blocked_by.deadline
string | null
Yes
runs[].blocked_by.maximumDurationSeconds
integer | null
Yes
runs[].id
string
Yes
The run's id — pass it to get_schedule_trigger_run.
runs[].trigger_id
string
Yes
Id of the schedule this run belongs to.
runs[].run_kind
"due" | "manual"
Yes
due = fired by the schedule; manual = started by a person.
runs[].status
"running" | "success" | "failed" | "cancelled"
Yes
Current state of the run.
runs[].started_at
string | null
Yes
ISO 8601 timestamp the run started.
runs[].completed_at
string | null
Yes
ISO 8601 timestamp the run settled; null while still running.
runs[].error
string | null
Yes
Failure text when the run failed or was skipped — for example a run skipped because the previous one was still in progress.
runs[].chat_conversation_id
string | null
Yes
Chat conversation holding the run's transcript, when linked.
runs[].runtime_task_id
string | null
Yes
Agent Runtime task id, when the run executed on the runtime.
Additional access requirement: Requires a user token. The caller must be the schedule actor, a project member, or someone with organization-wide Projects Can read access.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule the run belongs to.
run_id
string
Yes
Id of the run to read.
Output
Field
Type
Required
Description
blocked_by
object | null
Yes
Why this tick was skipped, including the blocking run and its frozen deadline.
blocked_by.phase
"starting" | "running" | "stopping"
Yes
blocked_by.runId
string | null
Yes
blocked_by.runtimeTaskId
string | null
Yes
blocked_by.startedAt
string
Yes
blocked_by.elapsedSeconds
integer
Yes
blocked_by.deadline
string | null
Yes
blocked_by.maximumDurationSeconds
integer | null
Yes
id
string
Yes
The run's id — pass it to get_schedule_trigger_run.
trigger_id
string
Yes
Id of the schedule this run belongs to.
run_kind
"due" | "manual"
Yes
due = fired by the schedule; manual = started by a person.
status
"running" | "success" | "failed" | "cancelled"
Yes
Current state of the run.
started_at
string | null
Yes
ISO 8601 timestamp the run started.
completed_at
string | null
Yes
ISO 8601 timestamp the run settled; null while still running.
error
string | null
Yes
Failure text when the run failed or was skipped — for example a run skipped because the previous one was still in progress.
chat_conversation_id
string | null
Yes
Chat conversation holding the run's transcript, when linked.
runtime_task_id
string | null
Yes
Agent Runtime task id, when the run executed on the runtime.
Additional access requirement: Requires a user token. The caller must be the schedule actor, or hold both organization-wide Projects Can read access and log:admin. Project membership or Projects read alone shows run status but not the transcript.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule the run belongs to.
run_id
string
Yes
Id of the run to read.
Output
Field
Type
Required
Description
run
object
Yes
run.blocked_by
object | null
Yes
Why this tick was skipped, including the blocking run and its frozen deadline.
run.blocked_by.phase
"starting" | "running" | "stopping"
Yes
run.blocked_by.runId
string | null
Yes
run.blocked_by.runtimeTaskId
string | null
Yes
run.blocked_by.startedAt
string
Yes
run.blocked_by.elapsedSeconds
integer
Yes
run.blocked_by.deadline
string | null
Yes
run.blocked_by.maximumDurationSeconds
integer | null
Yes
run.id
string
Yes
The run's id — pass it to get_schedule_trigger_run.
run.trigger_id
string
Yes
Id of the schedule this run belongs to.
run.run_kind
"due" | "manual"
Yes
due = fired by the schedule; manual = started by a person.
run.status
"running" | "success" | "failed" | "cancelled"
Yes
Current state of the run.
run.started_at
string | null
Yes
ISO 8601 timestamp the run started.
run.completed_at
string | null
Yes
ISO 8601 timestamp the run settled; null while still running.
run.error
string | null
Yes
Failure text when the run failed or was skipped — for example a run skipped because the previous one was still in progress.
run.chat_conversation_id
string | null
Yes
Chat conversation holding the run's transcript, when linked.
run.runtime_task_id
string | null
Yes
Agent Runtime task id, when the run executed on the runtime.
run.created_at
string
Yes
ISO 8601 creation timestamp.
session_id
string
Yes
The run's session id. Pass it to list_openappa_consults or list_openappa_yells.
conversation = the run's chat; interactions = rebuilt from its LLM calls; encrypted = the chat is encrypted and cannot be read here; runtime = it ran on the Agent Runtime, whose output is read on its run page; pending = it finished under a minute ago with nothing recorded yet; its record may still be written, so read it again shortly; none = nothing was recorded.
messages
object[]
Yes
The run's messages in order, with long values shortened.
messages[].role
string
Yes
messages[].parts
object[]
Yes
messages[].parts[].type
string
Yes
text, tool, or the UI part type when it is something else.
messages[].parts[].text
string
No
Message text, for a text part.
messages[].parts[].tool_name
string
No
Tool called, for a tool part.
messages[].parts[].tool_call_id
string
No
The tool call's id.
messages[].parts[].parent_tool_call_id
string
No
For a delegated agent's call, the delegation call that started that agent.
messages[].parts[].state
string
No
The tool call's final state.
messages[].parts[].input
string
No
The tool call's arguments as JSON.
messages[].parts[].output
string
No
The tool result as JSON, including any guardrails ruling.
messages[].parts[].error_text
string
No
The tool call's error text.
truncated
boolean
Yes
True when parts were left out to keep the result small.
Additional access requirement: Requires a user token. Only the schedule actor or someone with organization-wide Projects Can update access can perform this action. Project membership alone permits reading. See Granular Access Control.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule to enable.
Output
Field
Type
Required
Description
id
string
Yes
The trigger's id — pass it to get_schedule_trigger.
name
string
Yes
The trigger's name.
agent_id
string
Yes
Id of the agent the schedule runs.
agent_name
string | null
Yes
Name of that agent.
project_id
string | null
Yes
Project the schedule belongs to, when it is project-scoped.
cron_expression
string
Yes
5-part cron expression driving the schedule.
timezone
string
Yes
IANA timezone the cron expression is read in.
enabled
boolean
Yes
Whether the schedule is currently picked up when due.
last_executed_at
string | null
Yes
ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity.
Additional access requirement: Requires a user token. Only the schedule actor or someone with organization-wide Projects Can update access can perform this action. Project membership alone permits reading. See Granular Access Control.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule to disable.
Output
Field
Type
Required
Description
id
string
Yes
The trigger's id — pass it to get_schedule_trigger.
name
string
Yes
The trigger's name.
agent_id
string
Yes
Id of the agent the schedule runs.
agent_name
string | null
Yes
Name of that agent.
project_id
string | null
Yes
Project the schedule belongs to, when it is project-scoped.
cron_expression
string
Yes
5-part cron expression driving the schedule.
timezone
string
Yes
IANA timezone the cron expression is read in.
enabled
boolean
Yes
Whether the schedule is currently picked up when due.
last_executed_at
string | null
Yes
ISO 8601 timestamp of the last time the schedule fired, or null if it never has. Compare with run history when checking schedule activity.
Additional access requirement: Requires a user token. Only the schedule actor or someone with organization-wide Projects Can use access can perform this action. Project membership alone permits reading. See Granular Access Control.
Input
Parameter
Type
Required
Description
schedule_trigger_id
string
Yes
Id of the schedule to run.
Output
Field
Type
Required
Description
blocked_by
object | null
Yes
Why this tick was skipped, including the blocking run and its frozen deadline.
blocked_by.phase
"starting" | "running" | "stopping"
Yes
blocked_by.runId
string | null
Yes
blocked_by.runtimeTaskId
string | null
Yes
blocked_by.startedAt
string
Yes
blocked_by.elapsedSeconds
integer
Yes
blocked_by.deadline
string | null
Yes
blocked_by.maximumDurationSeconds
integer | null
Yes
id
string
Yes
The run's id — pass it to get_schedule_trigger_run.
trigger_id
string
Yes
Id of the schedule this run belongs to.
run_kind
"due" | "manual"
Yes
due = fired by the schedule; manual = started by a person.
status
"running" | "success" | "failed" | "cancelled"
Yes
Current state of the run.
started_at
string | null
Yes
ISO 8601 timestamp the run started.
completed_at
string | null
Yes
ISO 8601 timestamp the run settled; null while still running.
error
string | null
Yes
Failure text when the run failed or was skipped — for example a run skipped because the previous one was still in progress.
chat_conversation_id
string | null
Yes
Chat conversation holding the run's transcript, when linked.
runtime_task_id
string | null
Yes
Agent Runtime task id, when the run executed on the runtime.
