Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Available Tools

Reference for every tool the Erathos MCP server exposes.

This page lists every tool the Erathos MCP server exposes to an AI agent, grouped by what they operate on. Every tool is scoped to one workspace unless noted otherwise — get a valid workspace_id from list_workspaces first, then pass it explicitly to any other tool; nothing defaults to "the current workspace." Each entry below is collapsed by default — click a tool's name to expand its full parameters and return fields.

A few conventions hold across every tool:

  • IDs are consistent. A job_id, connection_id, workspace_id and so on returned by one tool means the same record wherever another tool takes a parameter of that name.

  • List tools paginate the same way. limit/offset page through results; keep raising offset by limit while meta.has_more is true.

  • meta.platform_url is a best-effort link to the same result in the platform, and meta.hint carries advice about the result when there is any (e.g. why a list came back empty).

  • Timestamps are in your own timezone. Every datetime a tool returns carries your UTC offset (the timezone get_me returns), as the platform shows them. Datetimes you pass in may use any offset.

Workspace & Identity

list_workspaces

List the workspaces the authenticated user belongs to, with the workspace_id every other tool takes. Membership is checked again on every call.

Example prompts

  • "Which workspaces do I have access to?"

  • "What's the workspace ID for Acme Corp?"

Parameters

  • No parameters.

Returns

  • results (list) — one entry per workspace:

    • workspace_id (string)

    • name (string)

get_me

Return the authenticated user's own identity. Useful for tools that act "as me," and for resolving the timezone metric buckets are shown in.

Example prompts

  • "Who am I logged in as?"

  • "What timezone is my account set to?"

Parameters

  • No parameters.

Returns

  • user_id (string)

  • email (string)

  • timezone (string, nullable) — the timezone every tool shows timestamps in, and the one get_workspace_metrics buckets times in.

  • meta.platform_url — link to the user's profile settings page.

Connections & Destinations

list_connections

List the source connections in a workspace, with where each one stands in its setup.

Example prompts

  • "What connections do I have set up in this workspace?"

  • "Which of my connections still need setting up?"

  • "Do any of my connections have failing jobs right now?"

Parameters

  • workspace_id (string, required)

  • connection_id (string, optional) — filter to one connection, e.g. to check on a setup while it validates.

  • is_api (boolean, optional) — filter to API-type connectors only.

  • is_database (boolean, optional) — filter to database-type connectors only.

Returns

  • results (list) — one entry per connection:

    • connection_id (string)

    • name (string)

    • source_connector_id (string) — the connector type (e.g. Postgres), as opposed to this one connection instance.

    • source_connector_name (string)

    • pipeline_id (string, nullable)

    • active_jobs (integer) — this connection's count of currently-active jobs.

    • failed_jobs (integer) — how many of those had their last run fail.

    • show_warning (boolean) — failed_jobs > 0.

    • has_valid_credentials (boolean, nullable) — null until the credentials are first checked, then whether the last check passed.

    • last_successful_connection_at (datetime, nullable) — null if a check has never passed.

    • setup_status (string) — the connection's next setup step:

      • awaiting_credentials — someone has to enter or fix its credentials in the platform (or save them again, if its settings' options were never loaded).

      • lost_authentication — credentials that worked before failed their last check; someone has to fix them in the platform, and its jobs can't run meanwhile.

      • validating — a background check is running (e.g. reading the schema); just wait.

      • needs_settings — choose its settings with configure_connection.

      • no_options_available — its credentials work but give access to no options for a setting it needs (e.g. no account visible to them); someone has to sign in with credentials that have access, then save them again.

      • schema_unavailable — its tables/endpoints, or its settings' options, couldn't be read, or none were found. The error from configure_connection/configure_jobs says what to check.

      • ready_for_jobs — create its jobs with configure_jobs.

      • no_destination — its jobs are set up, but the workspace has no working destination to load into (see get_destination).

      • configured — set up and able to run.

    • running_validation (string, nullable) — what the background check currently running is doing, in plain words (e.g. "checking its credentials").

  • meta.platform_url — link to the workspace's connections page.

list_source_connectors

List the connector types (e.g. "HubSpot", "Postgres") a source_connector_id can refer to — the discovery entrypoint for that id across list_jobs, list_runs, list_connections, and list_endpoints.

Example prompts

  • "What connector types are available for me to connect as a source?"

  • "Is there a HubSpot connector I can use?"

Parameters

  • workspace_id (string, required)

  • connector_id (string, optional) — filter to one connector type, e.g. to look up a source_connector_id seen in another tool.

  • name (string, optional) — substring search to resolve a connector by name (e.g. name='hubspot').

  • is_api (boolean, optional)

  • is_database (boolean, optional)

  • limit (integer, optional)

  • offset (integer, optional)

Returns

  • results (list) — one entry per connector type:

    • connector_id (string)

    • name (string)

    • description (string, nullable)

    • is_api (boolean)

    • is_database (boolean)

    • is_custom_connector (boolean) — true for a connector type private to this workspace, false for one available to every workspace.

    • release_stage (string, nullable) — the connector's own maturity: SOON, BETA, or STABLE.

    • docs_url (string, nullable)

  • meta.limit / meta.offset / meta.has_more — pagination.

  • meta.platform_url — link to where a human would pick one of these to start a new connection.

get_destination

Get the workspace's destination — the single data warehouse its pipelines load into. Errors if none has been created yet.

Example prompts

  • "What's our workspace's destination warehouse?"

  • "Are the destination's credentials still valid?"

Parameters

  • workspace_id (string, required)

Returns

  • destination_id (string)

  • name (string)

  • connector_id (string)

  • connector_name (string)

  • has_valid_credentials (boolean, nullable) — null until the first connection attempt, then true/false for whether the last attempt's credentials worked.

  • has_valid_schema (boolean, nullable) — same idea, but for the destination's schema/database setup. Both must be true for the destination to actually be usable.

  • last_successful_connection_at (datetime, nullable)

  • meta.platform_url — link to the destination in the platform.

list_destination_connectors

List the connector types (e.g. "Snowflake", "BigQuery") that can serve as a workspace's destination/warehouse.

Example prompts

  • "What warehouse types can I use as a destination?"

  • "Is BigQuery available as a destination option?"

Parameters

  • workspace_id (string, required)

  • connector_id (string, optional) — filter to one connector type.

  • name (string, optional) — substring search (e.g. name='snowflake').

  • is_api (boolean, optional)

  • is_database (boolean, optional)

  • limit (integer, optional)

  • offset (integer, optional)

Returns

  • results (list) — same shape as list_source_connectors's entries: connector_id, name, description (nullable), is_api, is_database, is_custom_connector, release_stage (nullable), docs_url (nullable).

  • meta.limit / meta.offset / meta.has_more — pagination.

  • meta.platform_url — link to the workspace's destination settings page.

create_connection

Create a new source connection in a workspace. This creates the connection shell only — the tool never accepts credentials as a parameter, since a credential passed as a tool argument would be visible to the agent and to the conversation. The human finishes the setup by entering credentials in the platform, at the link returned in meta.platform_url. Until they do, the connection has no valid credentials, and list_connections' setup_status says when it's ready for the next step.

Example prompts

  • "Create a new HubSpot connection called 'HubSpot - Marketing'."

  • "Set up a Postgres connection for our production database."

Parameters

  • workspace_id (string, required)

  • source_connector_id (string, required) — the connector type, from list_source_connectors.

  • name (string, required)

Returns

  • connection_id (string)

  • name (string)

  • source_connector_id (string)

  • source_connector_name (string)

  • meta.platform_url — link to the platform page where the human enters the connection's credentials.

  • meta.hint — if the credentials will be entered by someone without an Erathos account, use create_connection_secure_link instead of sharing platform_url.

create_destination

Create the workspace's destination. A workspace can have at most one, so this errors if it already has one (get_destination shows it; deleting it is only possible in the platform). Like create_connection, this creates the destination shell only and never accepts credentials; the human finishes the setup at meta.platform_url. Until they do, the destination has no valid credentials (has_valid_credentials is null in get_destination) and no pipeline can load into it.

Example prompts

  • "Set up BigQuery as our destination warehouse."

  • "Create a Snowflake destination called 'Analytics Warehouse'."

Parameters

  • workspace_id (string, required)

  • destination_connector_id (string, required) — the connector type, from list_destination_connectors.

  • name (string, required)

Returns

  • destination_id (string)

  • name (string)

  • connector_id (string)

  • connector_name (string)

  • meta.platform_url — link to the workspace's destination settings page, where the human enters the credentials.

  • meta.hint — if the credentials will be entered by someone without an Erathos account, use create_connection_secure_link (passing this destination_id as connection_id) instead of sharing platform_url.

create_connection_secure_link

Create a secure link that lets whoever holds it submit credentials for one connection or for the destination, without an Erathos account — for when the person who actually has the credentials (e.g. your company's DBA) isn't a platform user. Works for both credential-form connectors (username/password/API key) and OAuth-based ones; the recipient sees whichever the connector needs.

The link is single-use: it stops working as soon as credentials are submitted successfully, when it's revoked (see revoke_connection_secure_link), or when it expires.

Example prompts

  • "Create a link I can send to our DBA so they can enter the Postgres credentials."

  • "Generate a secure link for the Snowflake destination that's valid for 2 hours."

Parameters

  • workspace_id (string, required)

  • connection_id (string, required) — a connection from list_connections, or the destination's destination_id from get_destination.

  • ttl_hours (integer, optional, default 24) — how long the link stays valid. Use a shorter value if it will be sent through a less trusted channel, or a longer one if the recipient may not act on it right away.

Returns

  • share_link_id (string) — an 8-character id; use it with list_secure_links and revoke_connection_secure_link.

  • key (string)

  • expires_at (datetime, nullable)

  • meta.platform_url — the link to send to whoever will submit the credentials (not a link for you).

The link is shown only once, in this response. It isn't stored in recoverable form, so list_secure_links can't return it later. If it's lost before the recipient uses it, revoke it and create a new one.

list_secure_links

List the secure links created in a workspace, across every connection and the destination, or for just one of them. Use it to find a share_link_id to revoke, or to check whether a link has been used yet (and from which IP). The raw link itself is never returned.

Example prompts

  • "Has our DBA used the credentials link I sent yet?"

  • "Show me all the secure links still open in this workspace."

Parameters

  • workspace_id (string, required)

  • connection_id (string, optional) — limit the list to one connection or the destination.

  • share_link_id (string, optional) — filter to one link, e.g. to check whether a link just sent has been used.

Returns

  • results (list) — one entry per link, newest first:

    • share_link_id (string)

    • connection_id (string)

    • connection_name (string)

    • created_at (datetime)

    • expires_at (datetime, nullable)

    • consumed_at (datetime, nullable) — when credentials were submitted through the link; null if it hasn't been used.

    • consumed_from_ip (string, nullable)

    • revoked (boolean)

revoke_connection_secure_link

Revoke a secure link before it's used, so it stops working immediately. Revoking can't be undone — create a new link if one is needed again.

Example prompts

  • "Revoke the credentials link I sent yesterday."

  • "Cancel every unused secure link for the Postgres connection."

Parameters

  • workspace_id (string, required)

  • share_link_id (string, required) — from create_connection_secure_link or list_secure_links.

Returns

  • share_link_id (string)

  • revoked (boolean)

Connection Setup

Setting up a connection goes: create_connection → someone enters the credentials in the platform → configure_connection, only if the connection has settings to choose → configure_jobs → trigger_run. list_connections' setup_status says which step a connection is at.

The agent doesn't need to ask users about sync types or cursors. It asks what they need instead — how fresh the data must be, and whether they want each row's latest version or its history of changes — and passes on the plain-language explanations the tools return.

list_connection_settings

List a connection's own settings (e.g. which Google Ads ad account it reads from, or which Google Sheets files) and, for choice-type settings, the options to pick from.

Example prompts

  • "Which ad accounts can this Google Ads connection read from?"

  • "What settings does the new connection still need?"

Parameters

  • workspace_id (string, required)

  • connection_id (string, required)

  • setting_id (string, optional) — narrow the response to one setting.

  • name (string, optional) — search the options by value.

  • limit (integer, optional) / offset (integer, optional) — page through each setting's options separately.

Returns

  • connection_id (string)

  • is_configured (boolean) — whether the settings have been chosen.

  • running_validation (string, nullable) — what a background check still running on the connection is doing, if any (e.g. "loading the options for its settings").

  • settings (list) — one entry per setting:

    • setting_id (string)

    • name (string)

    • description (string, nullable)

    • example (string, nullable)

    • data_type (string)

    • accept_multiple_values (boolean)

    • is_required (boolean)

    • edit_mode (string) — what can still change once chosen: locked (never — a different value means a new connection) or append (it can only gain values, e.g. more files).

    • current_values (list of strings) — the values chosen so far.

    • options (list, nullable) — for a choice-type setting, each with option_id and value.

    • options_loaded (boolean, nullable) — false means the options haven't been loaded yet (the connection needs working credentials first), not that there are none. true with no options means the source offered none to these credentials; meta.hint says what to do.

    • options_has_more (boolean, nullable) — whether this setting has more options past limit.

configure_connection

Choose a connection's settings, from list_connection_settings. The first call chooses them and creates the connection's pipeline (named by name). After that, each setting's edit_mode decides what can change: a locked setting never can, and an append setting only gains values. A setting left out stays as it is, and repeating a call changes nothing. The connection's credentials must be validated first.

Most settings are locked once chosen — a different value later means creating a new connection. Confirm them before the first call, even when there's only one option.

Example prompts

  • "Use the 'Acme - Brazil' ad account for this Google Ads connection."

  • "Add these two spreadsheets to the Google Sheets connection."

Parameters

  • workspace_id (string, required)

  • connection_id (string, required)

  • settings (list, optional) — one entry per setting to set: setting_id plus values (for a choice-type setting, its option_ids, or an option's exact text when no other option shares it). For an append setting, pass just the new values: saved ones left out are kept, and ones already saved are skipped.

  • name (string, optional) — the pipeline's name, on the first call.

Returns

  • connection_id (string)

  • pipeline_name (string)

  • created (boolean) — whether this call created the pipeline.

  • settings (list) — every setting as saved now, each with setting_id, name, values, edit_mode.

  • added (list) — what this call added, same shape.

  • background_work_queued (boolean) — the platform queued a refresh for the new values (e.g. reading new files as tables); configure_jobs waits for it.

configure_jobs

Create or edit a connection's jobs — which tables (database) or endpoints (API) sync, and how — applying one set of settings to a whole selection. Call it again for other groups; later calls refine earlier ones.

It's a dry run by default: it returns a preview of exactly what would happen, to show to the user before calling again with dry_run=false. The preview goes through the same save the platform's manage-jobs page uses, and is then rolled back.

Example prompts

  • "Sync every table in the 'public' and 'sales' schemas, daily, keeping just the latest version of each row."

  • "Sync the 'deals' endpoint every hour."

  • "Stop syncing the 'email' column on the customers table."

Parameters

What to configure — combined with AND, at least one:

  • table_ids / endpoint_ids (list of strings, optional) — from list_tables/list_endpoints.

  • job_ids (list of strings, optional) — existing jobs, from list_jobs.

  • schema_names (list, optional) — whole schemas; null stands for tables outside any schema, as list_table_schemas reports them.

  • name_contains (string, optional)

  • select_all (boolean, optional, default false)

  • scope (string, optional, default all) — existing_only (only tables/endpoints that already have a job) or new_only (only those that don't).

How — every setting is optional. On an existing job, leaving one out keeps the current value; a new job gets the recommendation:

  • sync_frequency_id (string, optional) — from list_sync_frequencies. New jobs default to daily (or the plan's fastest allowed frequency, if daily isn't).

  • sync_time (string, optional) — HH:MM in the user's own timezone. New jobs default to 03:00.

  • sync_type (string, optional) — recommended (the default for new jobs: incremental where the table/endpoint supports it, full elsewhere), full, incremental_append, incremental_overwrite, or incremental_versioned.

  • incremental_mode (string, optional, default overwrite) — the incremental flavor recommended uses: overwrite keeps each row's latest version, versioned keeps a history of every change, append suits tables that only ever get new rows.

  • cursor_column (string or list of strings, optional, tables only) — the column(s) to track changes by. Naming them replaces the cursors of existing jobs too, resetting their progress. auto picks a common "last updated" column, and only for jobs that don't have any cursor yet.

  • cdc (boolean, optional) — on a database connection with CDC enabled, incremental tables sync through CDC by default (reading the database's change log, so they need a primary key but no cursor); cdc=false uses a cursor instead.

  • on_incremental_unavailable (string, optional, default skip) — what happens to tables/endpoints that can't sync incrementally as asked: skip reports them in needs_decision/full_only, and full configures them as full refresh on the fallback schedule.

  • fallback_sync_frequency_id / fallback_sync_time (string, optional) — that fallback schedule.

  • weekly_run_day (string, optional) — the day jobs on the weekly frequency run (default Sunday).

  • full_reload (string, optional) — a periodic full reload of the history, for incremental jobs syncing daily or more often: never (the default for new jobs), every_day, or a weekday.

  • columns (object, optional) — changes to the column selection, by name: exclude / include, anonymize / deanonymize.

  • enabled (boolean, optional)

  • dry_run (boolean, optional, default true)

Returns

  • dry_run (boolean)

  • pipeline (string) — existing, created, or will_create (a connection without settings gets its pipeline on the first save).

  • summary (list) — the resulting jobs, in groups that share the same settings:

    • sync_type (string), cdc (boolean), enabled (boolean), is_new (boolean)

    • cursor_columns (list of strings) — what changes are tracked by; empty for a full refresh, a CDC job, or a child endpoint that goes through its parent.

    • updated_through (string, nullable) — for a child endpoint without a cursor of its own, the parent endpoint whose filter decides what it fetches.

    • sync_frequency (string, nullable) and sync_time (string, nullable) — the frequency and the local time it runs at.

    • schedule (string) — when it runs, in plain words (e.g. "Every 6h, at 03:00, 09:00, 15:00 and 21:00").

    • count (integer) and names (list of strings) — how many tables/endpoints the group has, and which (e.g. public.orders).

    • explanation (string) — what this sync does, in plain language.

  • unchanged (integer) — selected jobs already as requested, which are left untouched.

  • fell_back_to_full (object, nullable) — jobs set to a full refresh because they can't sync incrementally: count, reason_counts, explanation.

  • needs_decision (list) — tables left out because they have no column matching the cursor asked for (or, with auto, no common "last updated" column) but could use another one. Each has entity_id, name, reason, options (full plus the columns it could track changes by) and explanation. At most 50 are listed; needs_decision_total (integer) counts them all, and list_table_columns with cursor_candidates_only=true lists every usable column.

  • full_only (object, nullable) — tables/endpoints left out because they can only sync in full: count, reason_counts, explanation. Reasons are no_primary_key, no_cursor, parent_not_eligible, or child_not_eligible.

  • impacts (list) — side effects on existing jobs, each with kind, count and explanation (e.g. a changed cursor reloads the full history; jobs outside the selection that follow a parent in it).

  • added_ancestors (list of strings) — parent endpoints added because a selected child needs them.

  • overridden_by_parent (integer) — child jobs whose schedule follows their parent instead of the one asked for.

  • columns_not_present_on (integer) — jobs where a column named in columns doesn't exist. That's not an error, since columns applies to the whole selection.

  • errors (list) — per-job errors, each with entity_id, name, messages.

  • plan — active_jobs_after, jobs_limit (nullable) and over_limit. Applying a change over the plan's job limit fails as a whole.

  • timezone (string) — the user's timezone, which sync_time is in.

  • removed_from_source (list) — the connection's jobs whose table/endpoint no longer exists at the source, each with job_id, name, enabled. They can't be configured, and stay active so their failing runs alert the user; disable_job stops them.

  • meta.platform_url — link to the connection's jobs in the platform.

Jobs & Runs

list_jobs

List the jobs (one per synced table/endpoint) in a workspace.

Example prompts

  • "What jobs are set up in this workspace?"

  • "Show me the jobs that are currently inactive."

  • "Which jobs haven't synced successfully in the last week?"

Parameters

  • workspace_id (string, required)

  • job_id (string, optional) — filter to one specific job.

  • connection_id (string, optional) — filter by one specific connection instance.

  • source_connector_id (string, optional) — filter by connector type (e.g. all jobs on any Postgres connection).

  • api_endpoint_id (string, optional)

  • company_table_id (string, optional) — a job has exactly one of api_endpoint_id/company_table_id set, never both.

  • is_active (boolean, optional)

  • sync_type (string, optional) — one of the values list_sync_types returns (e.g. incremental_overwrite).

  • sync_frequency_id (string, optional) — see list_sync_frequencies for valid values.

  • trigger_type (string, optional) — one of MANUAL, SCHEDULE, PARENT.

  • next_execution_before (datetime, optional)

  • freshness_before (datetime, optional) — jobs that haven't succeeded since this time (also matches jobs that have never succeeded). More expensive than the other filters — only pass it when you actually need to filter by staleness.

  • latest_error_after (datetime, optional) — jobs that have failed since this time. Also more expensive; same caveat as freshness_before.

  • limit (integer, optional)

  • offset (integer, optional)

Returns

  • results (list) — one entry per job:

    • job_id (string)

    • name (string, nullable)

    • is_active (boolean)

    • connection_id (string, nullable)

    • connection_name (string, nullable)

    • source_connector_id (string, nullable)

    • source_connector_name (string, nullable)

    • api_endpoint_id (string, nullable)

    • company_table_id (string, nullable)

    • sync_type (string, nullable) — the same values list_sync_types returns.

    • cdc (boolean) — whether it reads the database's change log instead of cursors.

    • source_removed (boolean) — its table/endpoint no longer exists at the source. It stays active so its failing runs alert the user; disable_job stops it.

    • sync_frequency_id (string, nullable)

    • sync_frequency (string, nullable) — its platform-facing description.

    • sync_time (string, nullable) — HH:MM in the user's timezone; null for a manually-run job.

    • schedule (string, nullable) — when the job runs, in plain words (e.g. "Every 6h, at 01:30, 07:30, 13:30 and 19:30, with a full reload on Sundays at 01:30").

    • trigger_type (string) — MANUAL, SCHEDULE, or PARENT.

    • next_execution_at (datetime, nullable)

    • freshness (datetime, nullable) — when the job's data was last successfully extracted; null if never.

    • freshness_run_id (string, nullable) — that run, for get_run.

    • latest_error (datetime, nullable) — when the job last failed.

    • latest_error_run_id (string, nullable) — that run, for get_run.

    • cursors (list) — the column(s)/field(s) its incremental sync tracks changes by (one or several), each with its current bookmark; empty for a full-refresh job or a CDC job. Each entry has field_id (nullable), field_name, field_type, value (nullable, as text).

  • meta.limit / meta.offset / meta.has_more — pagination.

  • meta.platform_url — link to the jobs in the platform.

list_runs

List a workspace's job runs (executions), most recent first.

Example prompts

  • "Show me the most recent runs for this workspace."

  • "Which runs failed today?"

  • "Show me all full-refresh runs for this connection."

Parameters

  • workspace_id (string, required)

  • job_id (string, optional)

  • run_id (string, optional)

  • connection_id (string, optional)

  • source_connector_id (string, optional)

  • parent_job_id (string, optional)

  • parent_run_id (string, optional)

  • status (string, optional) — one of BLOCKED, WAITING, QUEUED, EXECUTING, FINISHED, FAILED, CANCELED. The first four are still in flight; the last three are terminal.

  • trigger_type (string, optional)

  • is_full_refresh (boolean, optional) — whether the run did a full resync rather than an incremental one.

  • scheduled_after (datetime, optional) — filters by when the run was scheduled, not when it started/finished. Clamped to the workspace's plan-based retention window if it asks further back than the plan allows (or is left out).

  • scheduled_before (datetime, optional)

  • limit (integer, optional)

  • offset (integer, optional)

Returns

  • results (list) — one entry per run:

    • run_id (string)

    • job_id (string, nullable)

    • connection_id (string, nullable)

    • connection_name (string, nullable)

    • source_connector_id (string, nullable)

    • source_connector_name (string, nullable)

    • source_connector_type (string, nullable) — API or DATABASE.

    • name (string, nullable)

    • parent_job_id (string, nullable)

    • parent_run_id (string, nullable)

    • status (string)

    • trigger_type (string)

    • triggered_by (string, nullable) — the triggering user's email; internal Erathos staff emails are masked to a generic support address when viewed from a customer workspace.

    • is_full_refresh (boolean)

    • scheduled_at (datetime)

    • started_at (datetime, nullable)

    • finished_at (datetime, nullable)

    • duration_seconds (integer, nullable)

    • requests (integer) — source API requests made.

    • retries (integer)

    • retry_backoff_seconds (number)

    • rows (integer)

    • errors (list) — this run's own error log entries (only meaningful for a FAILED run), each with a details (string).

  • meta.limit / meta.offset / meta.has_more — pagination.

  • meta.paywalled_since (datetime, nullable) — set when scheduled_after was clamped forward to the workspace's plan-based retention window.

  • meta.platform_url — link to the workspace's runs page (pagination only; other filters aren't reflected in the link).

get_run

Get the full detail for one run — everything list_runs returns for it, plus data too heavy for a list row: a per-model metrics breakdown, every log entry (not just failures), the run's execution timeline, and its cursor bookmark snapshot.

Example prompts

  • "Why did this run fail? Show me the full details."

  • "Give me the complete log and timeline for that run."

Parameters

  • workspace_id (string, required)

  • run_id (string, required) — from list_runs, trigger_run, or a job's freshness_run_id/latest_error_run_id.

Returns

  • run — the same shape as one list_runs result entry.

  • metrics (list) — a breakdown per extracted model (the main one plus any nested sub-models, e.g. line items nested under an order — list_runs's own requests/retries/rows only ever reflect the main model). Each entry has model_name, is_nested_model (boolean), rows (integer), invalid_datatype_rows (integer), extract_requests (integer), load_requests (integer), extract_retries (integer), load_retries (integer), extract_backoff_seconds (number), load_backoff_seconds (number).

  • logs (list) — every log entry for this run, not just failures. If the run failed but has no logs of its own, its parent run's logs are returned instead (marked is_parent_error). Each entry has log_id, failed_at (datetime), failed_after_seconds (integer), is_parent_error (boolean), connector_stage (string, nullable), details (string, nullable), external_api_http_code (integer, nullable).

  • timeline (list) — the run's execution stages in order (e.g. connecting, requesting, parsing, loading). Each entry has execution_type, trace_type_name, trace_type_description, table_name (nullable), started_at (nullable), finished_at (nullable), duration_seconds (nullable), trace_count (integer), has_errors (boolean).

  • cursors (list) — this run's incremental-sync bookmark snapshot(s) as of when it ran (empty for a full-refresh run); same field name as list_jobs's own cursors, but for the job's bookmark at the time of this run rather than its current one. Each entry has field_id (nullable), field_name, field_type, value (nullable), manual_override (boolean).

  • webhook_deliveries (list) — what each orchestration webhook did after this run, one entry per webhook and table, in the same shape as list_webhook_deliveries. Empty when there were none, or when you can see runs but not webhooks.

  • meta.platform_url — link to the run in the platform; null if the run has no connection to link into.

list_sync_types

List the valid sync_type values a job can have, with their platform-facing description (e.g. full is labeled "Full Refresh") and a plain-language explanation of what each does. Not workspace-scoped — this is a small, fixed reference table.

Example prompts

  • "What sync types are available for a job?"

  • "What does the 'full' sync type mean?"

Parameters

  • No parameters.

Returns

  • result (list):

    • sync_type (string) — full, incremental_append, incremental_overwrite, or incremental_versioned; the same values list_jobs returns and configure_jobs takes.

    • description (string)

    • explanation (string)

list_sync_frequencies

List the valid sync_frequency_id values a job can have. Not workspace-scoped.

Example prompts

  • "What sync frequency options can I choose for a job?"

  • "Is there a manual, on-demand frequency option?"

Parameters

  • No parameters.

Returns

  • result (list):

    • sync_frequency_id (string)

    • description (string)

    • frequency_in_minutes (integer, nullable) — null for a manually-triggered, unscheduled frequency.

Selecting jobs for trigger, cancel, enable, and disable

trigger_run, cancel_run, enable_job, and disable_job all choose the jobs they act on the same way. Pass connection_id, job_ids (from list_jobs), or both — at least one is required:

  • connection_id only — acts on the connection's jobs (for trigger_run, every active top-level job; for the others, every job in the connection).

  • job_ids only — acts on exactly those jobs, even if they belong to different connections (e.g. every job named "orders" across several connections).

  • Both — acts on job_ids, but rejects the whole call if any of them don't belong to connection_id.

A job that can't be acted on is listed in skipped with a reason, and the rest of the call still goes through. The call only fails if nothing at all was acted on.

trigger_run

Trigger a manual run of a connection's jobs, or of specific jobs. See Selecting jobs above for how connection_id and job_ids combine.

When only connection_id is given and the connection itself can't run (invalid credentials, or an execution window that blocks manual runs), the whole call fails. When job_ids are given, jobs whose connection has one of those problems are skipped instead. The call also fails if the workspace has no destination or the destination's credentials are invalid, or if the run would exceed the plan's monthly limit of manual runs.

Example prompts

  • "Run all the jobs in the HubSpot connection now."

  • "Re-run the 'orders' job with a full refresh."

  • "Backfill the 'deals' job starting from January 1st."

Parameters

  • workspace_id (string, required)

  • connection_id (string, optional)

  • job_ids (list of strings, optional)

  • force_full_refresh (boolean, optional, default false) — re-extract the full history on incremental jobs instead of resuming from their cursor. Can't be combined with raw_cursor/timestamp_cursor.

  • raw_cursor (string, optional) — override the job's incremental bookmark with this value for this run (custom backfill).

  • timestamp_cursor (datetime, optional) — same as raw_cursor, for a timestamp bookmark. Pass only one of the two; both require a plan with custom backfill access.

  • enable_delete (boolean, optional, default false) — also delete destination rows that no longer exist at the source during this run.

Returns

  • triggered (list) — one entry per job that was queued: job_id, run_id (the new run, for get_run or list_runs), connection_id.

  • skipped (list) — one entry per job that wasn't queued: job_id, reason — one of not_found, inactive, webhook_triggered, invalid_connector_auth, window_blocked, already_running, source_removed (its table/endpoint no longer exists at the source, so a run could only fail).

cancel_run

Cancel the currently queued, waiting, or running executions of a connection's jobs, or of specific jobs. See Selecting jobs above for how connection_id and job_ids combine.

Canceling stops the job's running container (if any) and marks its execution as canceled. Data already written to the destination during the run is kept, and the job can be started again with trigger_run.

Example prompts

  • "Cancel everything that's running on the Postgres connection."

  • "Stop the 'orders' job's current run."

Parameters

  • workspace_id (string, required)

  • connection_id (string, optional)

  • job_ids (list of strings, optional)

Returns

  • canceled (list) — one entry per canceled job: job_id, run_id (the run that was canceled), connection_id.

  • skipped (list) — one entry per job that wasn't canceled: job_id, reason — not_found, or not_cancelable if nothing was queued or running for it.

enable_job

Enable a connection's jobs, or specific jobs, so they run on their schedule again. See Selecting jobs above for how connection_id and job_ids combine.

Enabling a job also enables every disabled job above it in the hierarchy (its parent, the parent's parent, and so on), the same as in the platform. Each job is checked against the workspace plan's limit on active jobs, counting those parent jobs too. Jobs are processed in the order given, so if the limit is reached partway through, the earlier jobs are enabled and the rest are skipped.

Enabling also checks the job's rules again: a CDC job can't be enabled while its connection's CDC is turned off, and a job whose table/endpoint no longer exists at the source isn't enabled, since its runs could only fail.

Example prompts

  • "Turn the 'orders' and 'customers' jobs back on."

  • "Re-enable every job in the Salesforce connection."

Parameters

  • workspace_id (string, required)

  • connection_id (string, optional)

  • job_ids (list of strings, optional)

Returns

  • enabled (list) — one entry per enabled job: job_id, connection_id, cascaded_job_ids (list of strings — the parent jobs that were enabled along with it).

  • skipped (list) — one entry per job that wasn't enabled: job_id, reason, and detail (nullable, how to fix it, where there is a fix). Reasons:

    • not_found

    • already_enabled

    • enabled_via_cascade — enabled as a parent of an earlier job in the same call, so it ends up enabled too.

    • jobs_limit_exceeded

    • cdc_unavailable — a CDC job on a connection whose CDC was turned off.

    • source_removed — its table/endpoint no longer exists at the source.

disable_job

Disable a connection's jobs, or specific jobs, so they stop running on their schedule. See Selecting jobs above for how connection_id and job_ids combine.

Disabling a job also disables every job below it in the hierarchy, and cancels their queued or waiting next runs. A run that's already executing is left alone — use cancel_run to stop it.

Example prompts

  • "Pause every job in the HubSpot connection."

  • "Disable the 'events' job, it's not needed anymore."

Parameters

  • workspace_id (string, required)

  • connection_id (string, optional)

  • job_ids (list of strings, optional)

Returns

  • disabled (list) — one entry per disabled job: job_id, connection_id, cascaded_job_ids (list of strings — the child jobs that were disabled along with it).

  • skipped (list) — one entry per job that wasn't disabled: job_id, reason — one of not_found, already_disabled, disabled_via_cascade (already disabled as a child of another job in the same call).

Schema Discovery

list_endpoints

List the endpoints (resources/tables, e.g. "deals", "contacts") an API connector exposes.

Example prompts

  • "What endpoints does our HubSpot connector expose?"

  • "Does the 'deals' endpoint have any child endpoints?"

Parameters

  • workspace_id (string, required)

  • source_connector_id (string, required)

  • endpoint_id (string, optional) — filter to one endpoint, e.g. to look up an api_endpoint_id from list_jobs.

  • parent_endpoint_id (string, optional) — filters to the direct children of one endpoint, for walking the hierarchy top-down; omit to see all of them flattened.

  • name (string, optional) — substring search (e.g. name='deal').

  • limit (integer, optional)

  • offset (integer, optional)

Returns

  • results (list) — one entry per endpoint:

    • endpoint_id (string)

    • connector_id (string)

    • name (string)

    • parent_endpoint_id (string, nullable)

    • description (string, nullable)

    • has_children_endpoints (boolean) — whether drilling into it with parent_endpoint_id is worth it.

    • has_custom_fields (boolean) — whether the endpoint also picks up a connection's own custom fields (see list_custom_fields).

  • meta.limit / meta.offset / meta.has_more — pagination.

list_endpoint_fields

List the base fields (the connector type's own schema) of one endpoint, or of every endpoint in an API connection. A connection's own custom fields are listed by list_custom_fields.

Example prompts

  • "What fields are on the 'deals' endpoint?"

  • "Which fields in this HubSpot connection are dates?"

Parameters

  • workspace_id (string, required)

  • endpoint_id (string, optional) — one endpoint, from list_endpoints.

  • connection_id (string, optional) — every endpoint of this API connection, when passed without endpoint_id. At least one of the two is required.

  • name (string, optional) — substring search (e.g. name='owner').

  • field_type (string, optional) — case-insensitive substring match on the type the connector reports (e.g. field_type='date' matches date and datetime).

  • limit (integer, optional)

  • offset (integer, optional)

Returns

  • results (list) — one entry per field:

    • field_id (string)

    • connector_id (string)

    • endpoint_id (string)

    • endpoint_name (string)

    • name (string)

    • field_type (string, nullable) — whatever the connector itself reports; free text, not a fixed set of values.

    • is_nullable (boolean)

    • example (string, nullable)

    • description (string, nullable)

    • is_primary_key (boolean)

    • is_cursor_available (boolean)

  • meta.limit / meta.offset / meta.has_more — pagination.

list_custom_fields

List an API connection's own custom fields (e.g. a CRM's custom properties) — fields beyond its connector type's base schema, which list_endpoint_fields lists.

Example prompts

  • "What custom properties does our HubSpot account have?"

  • "Which custom fields does the 'deals' endpoint pick up?"

Parameters

  • workspace_id (string, required)

  • connection_id (string, required)

  • endpoint_id (string, optional) — narrow to the custom fields that endpoint picks up (none unless list_endpoints says has_custom_fields is true). Without it, every custom field of the connection is listed.

  • name (string, optional) — substring search.

  • field_type (string, optional) — case-insensitive substring match on the type the source reports.

  • limit (integer, optional)

  • offset (integer, optional)

Returns

  • results (list) — one entry per custom field:

    • field_id (string)

    • connection_id (string)

    • field_key (string)

    • name (string)

    • field_type (string, nullable)

    • is_nullable (boolean)

    • example (string, nullable)

    • description (string, nullable)

    • endpoint (string) — the endpoint text the field was recorded against.

  • meta.limit / meta.offset / meta.has_more — pagination.

list_table_schemas

Summarize one database connection's tables by schema — a cheap first look at a large database, e.g. to ask which schemas to sync before passing them to configure_jobs.

Example prompts

  • "Which schemas does our Postgres database have, and how big are they?"

Parameters

  • workspace_id (string, required)

  • connection_id (string, required)

Returns

  • results (list) — one entry per schema:

    • schema_name (string, nullable) — null for tables outside any schema.

    • table_count (integer)

list_tables

List the tables (e.g. "public.orders") one database connection exposes. Only tables whose columns have already been introspected are returned.

Example prompts

  • "What tables are available in our Postgres connection?"

  • "Show me the tables in the 'public' schema."

Parameters

  • workspace_id (string, required)

  • connection_id (string, required)

  • table_id (string, optional) — filter to one table, e.g. to look up a company_table_id from list_jobs.

  • schema_name (string, optional) — filters to one schema (e.g. 'public'); omit to see tables across all schemas.

  • name (string, optional) — substring search on the table name (e.g. name='order').

  • limit (integer, optional)

  • offset (integer, optional)

Returns

  • results (list) — one entry per table:

    • table_id (string)

    • connection_id (string)

    • schema_name (string, nullable)

    • name (string)

  • meta.limit / meta.offset / meta.has_more — pagination.

list_table_columns

List the columns of one table, or of every table in a database connection (e.g. to find all its date columns at once). Each column names its table.

Example prompts

  • "What columns does the 'orders' table have?"

  • "Which columns in our database could track when a row last changed?"

Parameters

  • workspace_id (string, required)

  • table_id (string, optional) — one table, from list_tables.

  • connection_id (string, optional) — every table of this connection, when passed without table_id. At least one of the two is required.

  • name (string, optional) — substring search (e.g. name='email').

  • field_type (string, optional) — case-insensitive substring match on the column's type as the database reports it (e.g. field_type='date' matches DATE and DATETIME; 'time' matches TIMESTAMP too).

  • cursor_candidates_only (boolean, optional, default false) — keep only the columns usable to track changes by (the ones configure_jobs' cursor_column accepts), e.g. to pick one for tables in needs_decision.

  • limit (integer, optional)

  • offset (integer, optional)

Returns

  • results (list) — one entry per column:

    • column_id (string)

    • connection_id (string)

    • table_id (string)

    • schema_name (string, nullable)

    • table_name (string)

    • name (string)

    • field_type (string)

    • is_nullable (boolean)

    • example (string, nullable)

    • description (string, nullable)

    • comments (string, nullable)

    • is_primary_key (boolean)

    • is_cursor_available (boolean)

  • meta.limit / meta.offset / meta.has_more — pagination.

Metrics

get_workspace_metrics

Aggregate a workspace's metrics over time, broken down by time and by entity (workspace-wide, per connection, or per job).

Example prompts

  • "How many rows have we processed this month?"

  • "Which connections had the most errors last week?"

  • "What does our sync activity look like by hour of day?"

Parameters

  • workspace_id (string, required)

  • metric (string, required) — what's counted: rows (rows processed), retries (source API retries), runs (runs no longer queued/waiting/executing), successes (finished runs), errors (failed runs).

  • time_level (string, required) — hourly, daily, monthly (a timeline); or weekday/hour_of_day (fold the whole range into 7/24 fixed buckets to show a recurring pattern). Buckets use the user's own timezone, not UTC.

  • entity_level (string, required) — workspace (one total per bucket), connection, or job (broken out per connection/job).

  • entity_id (string, optional) — scope to just one connection/job (not valid with entity_level='workspace').

  • start_date (string, optional, ISO 8601) — clamped to the workspace's plan-based retention window if it asks further back than the plan allows.

  • end_date (string, optional, ISO 8601, exclusive) — the range defaults to, and is capped at, a window sized by time_level/entity_level (tighter for finer buckets and for jobs), even for weekday/hour_of_day.

  • entity_limit (integer, optional, default 10, max 50) — without entity_id, how many entities to return, ranked by their total over the range.

  • entity_offset (integer, optional) — pages further down the same ranking.

  • rank_order (string, optional, default top) — top for the busiest entities, bottom for the least active ones (e.g. finding idle jobs).

Returns

  • results (list) — one entry per time bucket (and per entity, if broken out): time_bucket (string), value (integer), entity_id (string, nullable).

  • entities (map) — keyed by entity_id, each with connection_name (nullable), job_name (nullable), connection_id (nullable, a job's parent connection), rank (integer, nullable, its 1-indexed position in the full ranking), total (integer, nullable, its summed value over the whole range), deleted (boolean, nullable, true if the connection/job has since been deleted — its history still counts, but it's gone from list_connections and the platform).

  • paywalled_since (string, nullable) — set if start_date was clamped by the plan's retention window.

  • meta.start_date / meta.end_date / meta.entity_limit / meta.entity_offset / meta.timezone / meta.results_count — the values actually applied, not just an echo of your input.

Orchestration Webhooks

An orchestration webhook is an HTTP request Erathos sends after a job's run finishes, to start the next step in another tool, such as an Airflow DAG or a dbt Cloud job. It's sent once per table the run synced, and only when all of its rules pass. A webhook covers the jobs it's linked to, and every job of the connections it's linked to, including jobs added to them later. See Trigger jobs outside Erathos for how webhooks work.

These tools need your workspace's plan to include orchestration. A few safeguards apply when the agent writes webhooks:

  • Credentials are never typed into the conversation. A webhook references them as ${{secrets.NAME}}, and the agent refuses a header or URL with a literal credential in it. Secrets are created through the developer API for now, so their values never pass through the agent.

  • The agent confirms the destination with you before creating a webhook or changing where it's sent, since the request carries details of your runs.

  • Webhooks only go to public addresses. A webhook pointing to a private, loopback or link-local address is refused when it's sent.

list_orchestration_webhooks

List a workspace's orchestration webhooks, with each one's last delivery.

Example prompts

  • "Which webhooks fire after my Postgres connection's jobs?"

  • "Are any of my webhooks failing?"

Parameters

  • workspace_id (string, required)

  • job_id (string, optional) — webhooks that fire for this job, linked to it or to its connection.

  • connection_id (string, optional) — webhooks linked to this connection or to any of its jobs.

  • is_active (boolean, optional)

  • webhook_id (string, optional) — filter to one webhook.

  • limit (integer, optional)

  • offset (integer, optional)

Returns

  • results (list) — one entry per webhook:

    • webhook_id (string)

    • description (string)

    • is_active (boolean)

    • method (string)

    • target_host (string, nullable) — the URL's host as written, which may be a ${{variables.NAME}} reference.

    • job_count (integer) / connection_count (integer) — what it's linked to.

    • rule_count (integer)

    • created_at / updated_at (datetime)

    • last_delivery_status (string, nullable) / last_delivery_at (datetime, nullable) — its most recent delivery within your plan's history window.

  • meta.limit / meta.offset / meta.has_more — pagination.

get_orchestration_webhook

Show one webhook in full: its request, rules, and the jobs and connections it fires for.

Example prompts

  • "Show me the full configuration of the Airflow webhook."

  • "Which rules decide when this webhook is sent?"

Parameters

  • workspace_id (string, required)

  • webhook_id (string, required)

Returns

  • webhook_id, description, is_active, method — as in list_orchestration_webhooks.

  • url (string), header (object, nullable), body (object, nullable) — may contain ${{variables.NAME}}, ${{secrets.NAME}} and ${{erathos.name}} references. A credential written literally instead of as a secret reference is replaced by [redacted].

  • redacted_fields (list) — where something was redacted (e.g. header.Authorization). The agent can suggest moving it into a secret.

  • rules (list) — each with variable_name, operation and value (a string, or a list for IN/NOT_IN). Every rule must pass for the webhook to be sent.

  • job_ids (list) / connection_ids (list) — what it fires for.

  • created_at / updated_at (datetime)

configure_orchestration_webhook

Create a webhook, or change one. Without webhook_id it creates one; with it, only the fields passed change. To stop a webhook firing, disable it with is_active: false, which can be undone, rather than deleting it.

Example prompts

  • "After my orders table syncs successfully, trigger the daily_orders DAG in Airflow."

  • "Make that webhook fire for every job of the Postgres connection, including new tables."

  • "Only send it when rows were loaded."

  • "Pause the dbt webhook."

Parameters

  • workspace_id (string, required)

  • webhook_id (string, optional) — the webhook to change; omit to create one.

  • description (string, optional) — required when creating.

  • url (string, optional) — required when creating. http:// or https://, and may contain references anywhere, the host included.

  • method (string, optional) — POST, PUT, PATCH, GET or DELETE. Required when creating.

  • header (object, optional) — e.g. {"Authorization": "Bearer ${{secrets.AIRFLOW_TOKEN}}"}. Pass {} to clear it.

  • body (object, optional) — pass {} to clear it.

  • rules (list, optional) — each {variable_name, operation, value}, using the operations and value formats list_run_metadata_variables gives. Replaces all current rules when passed; [] removes them, so the webhook fires after every run.

  • job_ids (list, optional) / connection_ids (list, optional) — what it fires for. A webhook needs at least one job or connection. Each replaces the current list when passed.

  • is_active (boolean, optional)

The agent can't save a webhook that has a literal credential, references a variable, secret or metadata field that doesn't exist, has a reference missing its $, or points to an obviously non-public address. It explains what to fix instead.

Returns

  • created (boolean) — whether a new webhook was created.

  • target_host (string, nullable) — where it sends, as written.

  • webhook — the saved webhook, in the same shape as get_orchestration_webhook.

delete_orchestration_webhook

Delete a webhook for good. Your AI client should ask you to confirm before it runs; to only stop a webhook firing, disable it with configure_orchestration_webhook instead.

Example prompts

  • "Delete the old test webhook."

Parameters

  • workspace_id (string, required)

  • webhook_id (string, required)

Returns

  • webhook_id (string)

  • description (string)

  • deleted (boolean)

list_webhook_deliveries

List what happened to webhooks after each run, newest first: one entry per webhook, run and table. It answers "why didn't my webhook fire?" and "is it failing?".

Example prompts

  • "Why didn't my Airflow DAG start after last night's sync?"

  • "Has the dbt webhook failed this week?"

  • "Show me the webhook deliveries for this run."

Parameters

  • workspace_id (string, required)

  • webhook_id (string, optional)

  • job_id (string, optional)

  • connection_id (string, optional) — deliveries for any job of this connection.

  • run_id (string, optional) — the same run_id the run tools take.

  • status (string, optional) — SKIPPED, SUCCEEDED, FAILED or BLOCKED.

  • target_host (string, optional) — the resolved host, e.g. airflow.acme.com.

  • delivered_after / delivered_before (datetime, optional) — clamped to your plan's history window, like runs.

  • limit (integer, optional)

  • offset (integer, optional)

Returns

  • results (list) — one entry per delivery:

    • delivery_id, webhook_id, webhook_description

    • status (string) — SKIPPED (its rules didn't pass), SUCCEEDED (sent, 2xx response), FAILED (non-2xx response, timeout or network error), or BLOCKED (refused because the host isn't a public address).

    • failed_rules (list, nullable) — for SKIPPED: each rule that didn't pass, with variable_name, operation, expected and the run's actual value.

    • run_id, job_id, table (string)

    • delivered_at (datetime)

    • target_host_template (string, nullable) — the host as written; target_host (string, nullable) — the resolved host, null when it came from a secret; target_host_ip (string, nullable)

    • http_status (integer, nullable), error (string, nullable), duration_ms (number, nullable)

  • meta.limit / meta.offset / meta.has_more — pagination.

  • meta.paywalled_since (datetime, nullable) — set when your plan's history window hid older deliveries.

list_run_metadata_variables

List the run metadata a webhook can use: each value's ${{erathos.name}} placeholder for the URL, header or body, and, for those rules can use, the operations and value format a rule takes. Not workspace-scoped.

Example prompts

  • "What run details can I send in a webhook?"

  • "How do I write a rule that only fires on weekdays?"

Parameters

  • usable_in_rules (boolean, optional) — only metadata rules can, or can't, use.

Returns

  • results (list):

    • name (string) and placeholder (string), e.g. ${{erathos.rows}}

    • description (string)

    • data_type (string)

    • usable_in_rules (boolean)

    • rule_variable_name (string, nullable) — the rule's variable_name, e.g. ROWS.

    • rule_operations (list) — the operations a rule on it accepts.

    • rule_value_format (string, nullable) — how to write the rule's value.

list_workspace_variables

List a workspace's variables: named values webhooks reference as ${{variables.NAME}}, such as a tool's base URL. Values are shown.

Example prompts

  • "Which variables are set up in this workspace?"

Parameters

  • workspace_id (string, required)

  • name (string, optional) — a substring search on the name.

  • limit (integer, optional)

  • offset (integer, optional)

Returns

  • results (list) — variable_id, name, value, placeholder (e.g. ${{variables.AIRFLOW_HOST}}), created_at, updated_at.

  • meta.limit / meta.offset / meta.has_more — pagination.

list_workspace_secrets

List a workspace's secrets by name: credentials webhooks reference as ${{secrets.NAME}}. Values are never shown, here or anywhere else.

Example prompts

  • "Is there already a secret for the Airflow token?"

Parameters

  • workspace_id (string, required)

  • name (string, optional) — a substring search on the name.

  • limit (integer, optional)

  • offset (integer, optional)

Returns

  • results (list) — secret_id, name, placeholder (e.g. ${{secrets.AIRFLOW_TOKEN}}), created_at, updated_at (nullable for older secrets).

  • meta.limit / meta.offset / meta.has_more — pagination.

Support

contact_support

Open a ticket with the Erathos support team on your behalf, for a problem the agent couldn't solve with the other tools. It's the same kind of ticket the chat in the platform opens, so you follow it under Recent tickets in the platform's chat, and replies reach you there and by email. They can't be read back through the agent.

The agent calls this only when you ask for human help, or agree to it after it couldn't fix the problem. It should show you the title and message before sending. Erathos adds the details of the run, job and connection involved (status, errors and a link to the platform) itself, so you don't need to copy them in. Values that look like credentials are masked before sending, but don't put passwords or keys in the message.

You can open at most one ticket per run and 5 tickets per day.

Example prompts

  • "This run keeps failing and I don't know why. Open a ticket with Erathos support."

  • "The orders table is missing rows even though the job succeeds. Ask support to look into it."

  • "Request a Pipedrive source connector from Erathos."

Parameters

  • workspace_id (string, required)

  • title (string, required) — a short summary of the problem, used as the ticket's title (up to 200 characters).

  • message (string, required) — the problem in your words, plus what the agent found (up to 5,000 characters).

  • category (string, optional, default other) — picks the ticket type:

    • run_failure — a failed run. Requires run_id.

    • data_inconsistency — runs succeed but rows are missing, extra or wrong. Requires job_id, run_id or connection_id.

    • connector_request — a connector Erathos doesn't have yet. Requires connector_request.

    • feature_request — an idea for a new feature.

    • connection_setup, billing or other — anything else.

  • run_id (string, optional) — the run the ticket is about, from list_runs or get_run.

  • job_id (string, optional) — the job the ticket is about, from list_jobs.

  • connection_id (string, optional) — the connection the ticket is about, from list_connections. When more than one of run_id, job_id and connection_id is given, they must belong to the same connection.

  • steps_already_tried (string, optional) — what was already done, e.g. re-ran the job or refreshed the credentials.

  • connector_request (object, optional) — only for connector_request:

    • connector_name (string, required) — the tool or database you want to connect.

    • kind (string, required) — api or database.

    • role (string, required) — source (extract data from it) or destination (load data into it).

    • documentation_url (string, optional) — the API's documentation.

    • endpoints (string, optional) — the endpoints you need data from.

Returns

  • ticket_id (string) — the ticket number, as shown in the platform's chat.

  • ticket_type (string) — e.g. Failed job, Data inconsistencies, Connector request, Feature request or General ticket.

  • status (string) — the ticket's status as you see it, e.g. Submitted.

PreviousHow to Connect
NextAPIs

Last updated