validate_package, records a validation and writes a workflow’s script to S3, noted on its entry, but it never alters a pipeline.) Some of them (schema discovery, previews, connection tests, docs lookup) reach out to an external service on each call, so use those sparingly. Tools that create, edit, run, or schedule pipelines are documented on the Building & Editing Packages and Jobs & Schedules pages.
Tool index
Account inventory
list_connections
Read-only. Lists database and cloud-storage connections in the current account. By default only active connections are returned; archived connections (for example, an OAuth connection whose token refresh failed) are hidden, the same way they are removed from the dashboard. Credentials and connection-specific properties are never returned.string
Filter by connection type. Accepts short names like
postgres or s3 (the same vocabulary get_connection uses), and the corresponding STI class names like PostgresDatabaseConnection for backward compatibility.string
default:"active"
Which connections to list. One of
active or archived.integer
default:"50"
Maximum connections to return. 1 to 200.
integer
default:"0"
Number of connections to skip, for paging.
array
Each entry includes
id, name, type (short form), and status only.object
offset, limit, and returned (the count in this page).get_connection
Read-only. Returns details for a single connection by id. Credentials, TLS certificates, and SSL keys are never returned, only a curated set of non-credential identifying fields.integer
required
The connection id.
string
Short name (for example
postgres, amazon_s3) or STI class name. Only needed to disambiguate a rare id collision across the database and cloud-storage tables.integer
The connection id.
string
The connection name.
string
Short type identifier, for example
postgres or amazon_s3.string
Connection status.
integer
The owning user id.
string
ISO 8601 creation timestamp.
string
ISO 8601 last-updated timestamp.
object
Non-credential identifying fields, present when set:
host, port, database, tunnel_type, local_port, plus allowlisted properties (schema, region, account_name, warehouse, s3_staging_dir, auth_method, ssl).object
The source and destination component types to use for this connection (for example a Snowflake connection suggests
snowflake_destination_component, not the generic database component). Absent when there is no suggestion.list_workspaces
Read-only. Lists workspaces in the current account. Workspaces are the recommended starting point for orienting on what work exists. The activity counts come from a cached reporting table, so they are a snapshot, not realtime.integer
default:"50"
Maximum workspaces to return. 1 to 200.
integer
default:"0"
Number of workspaces to skip, for paging.
array
Each entry includes
id, name, description, package_count, last_failed_jobs_count, last_completed_jobs_count, last_stopped_jobs_count, created_at, and updated_at.object
offset, limit, and returned.list_packages
Read-only. Lists package definitions (ETL pipelines) in the current account. Defaults to active packages. Includes two quality signals (last_run_status and last_validation) so an agent can prefer healthy packages when picking a reference template.
integer
default:"50"
Maximum packages to return. 1 to 200.
integer
default:"0"
Number of packages to skip, for paging.
string
Filter by flow type. One of
dataflow (single-stage data movement) or workflow (multi-stage orchestration).string
default:"active"
Filter by status. One of
active or archived.integer
Restrict to packages in a single workspace.
array
Each entry includes
id, name, description, flow_type, status, workspace_id, version, version_description, owner_id, last_run_status, last_validation ({valid, status, errors_count, validated_at} or null), created_at, and updated_at.object
offset, limit, and returned.get_package
Read-only. Returns a single package by id. By default you get a curated flow-graph summary (component count, edge count, component-type tally, component names, variable count). Request the full graph to get the completedata_flow_json.
A package has two layers: the saved version (what jobs and schedules run) and the caller’s draft (unpublished edits, what the editor canvas shows). get_package returns whichever layer holds the caller’s latest edits, and graph_source names it ('draft' or 'saved'). The version and version_description fields always describe the saved version, even when graph_source is 'draft'. A package can read version: 1.0 with an empty saved flow while the draft holds a full pipeline. Use graph_source when describing a canvas, not version.
integer
required
The package (job) id.
boolean
default:"false"
Return the full
data_flow_json blob instead of just the summary. Inline secrets (REST ?api_key= query params, Authorization headers, basic-auth passwords, secrets in bash/script bodies) are masked as [REDACTED] server-side before the graph leaves the tool. See Inline secret redaction in get_package.integer
The package id.
string
The package name.
string
dataflow or workflow.string
Package status.
string
Status of the most recent run, or
null if never run.object
Most recent validation as
{valid, status, errors_count, validated_at}, or null if never validated.object
Summary of the flow graph:
component_count, edge_count, variables_count, component_types (a per-type tally), and component_names (the components’ user-authored labels, capped at 100 entries — component_count beside it stays exact, so a name’s absence from a capped list does not mean the component is missing). null if the graph is missing or malformed. Also returned: description, workspace_id, version, version_description, owner_id, created_at, updated_at.string
Which layer the
graph and data_flow_json describe. 'draft' when the response reflects the caller’s unpublished edits (the editor canvas). 'saved' when it reflects the running version. Falls back to 'saved' when a draft read fails.boolean
true when the caller has an unpublished draft on this package and its flow is non-empty. false when the response describes the saved version.integer
The saved
version number the draft was branched from. null when has_unsaved_draft is false.string
ISO 8601 timestamp (microsecond precision) of the last write to the draft. Matches the shape emitted by
add_package_components, remove_package_components, update_package_components, and update_package_edges, so you can compare it across tools to detect whether the draft changed between calls. null when has_unsaved_draft is false.object
The full graph. Present only when
include_full_graph is true, with inline secret values redacted. Describes the same layer named by graph_source.list_clusters
Read-only. Lists compute clusters (the resources package runs execute on) in the current account. Defaults to active clusters only; terminated, terminating, and pending-terminate clusters are hidden unless you pass an explicitstatus. Ordered most-recently-created first.
integer
default:"50"
Maximum clusters to return. 1 to 200.
integer
default:"0"
Number of clusters to skip, for paging.
string
Filter by status (for example
available, idle, terminated). When omitted, only active clusters are returned.array
Each entry includes
id, name, description, status, type, nodes, region, plan_id, owner_id, terminate_on_idle, time_to_idle, and lifecycle timestamps (launched_at, available_since, idle_since, terminated_at, created_at, updated_at).object
offset, limit, and returned.search_all
Read-only. Searches across connections, packages, clusters, and workspaces using free text, so you can locate the right record without iterating throughlist_* calls. Runs (job executions) are intentionally excluded: use list_runs with a status filter for those.
string
required
The free-text search query.
array
Which resource categories to search. Any of
connection, package, cluster, workspace. Defaults to all four.integer
default:"10"
Maximum hits per resource type. 1 to 50.
object
Matching records grouped by type. Connection hits carry
connection_type; package hits carry flow_type and status; cluster hits carry status; workspace hits carry description. Every hit includes type, id, and name.integer
Total number of hits across all searched types. Also returned:
query and per_type_limit.Pipeline diagnostics
validate_package
Read-only from the agent’s point of view, but not free of side effects. Validates a package without running it: a structural check followed by a Job Management Service (JMS) script validation, returning the per-component error list. Each call creates aJobValidation record and makes a network call to JMS (typically about 5 seconds, up to a few minutes for very large packages), and for workflow packages writes the script and variables to S3. It counts against the mutation rate-limit cap. Use it as a pre-flight check before running a package.
integer
required
The package (job) id to validate.
boolean
true when the package validates (status completed with no errors).string
The validation status, for example
completed or failed.array
The raw validation error list.
array
Errors mapped to the named component and field, with suggested fixes.
string
A human-readable summary of the validation outcome.
array
Suggested next steps to reach a valid package. Also returned:
validation_id, package_id, status_message, runtime_seconds, and validated_at.validate_expression
Read-only. Returns no account data. Evaluates a single Pig expression and returns its computed value or a syntax error. It has no source-column context, so expressions that reference input fields must be checked withpreview_transformation instead.
string
required
The Pig expression, for example
ADDDURATION(NOW(),'P1D') or UPPER($name). Max 4000 characters.object
A map of
$var name to sample value. Quote string literals, for example { "name": "'Al'" }.boolean
true with a result, or false with an error.The evaluated value, when
valid is true.string
The syntax or validation error, when
valid is false. Also returned: expression (echoed back).discover_schema
Read-only. Database connections only. Lists the tables available through a database connection (Postgres, MySQL, Snowflake, and so on). Cloud-storage and SaaS connections return an error; usediscover_file_schema for files. Each call hits the schema-importer over the network and issues a metadata query against the customer’s database, so use sparingly.
integer
required
A database connection id from
list_connections.string
Narrow to a single schema, for example
public for Postgres.integer
default:"50"
Maximum tables to return. 1 to 200.
integer
default:"0"
Number of tables to skip, for paging.
string
Substring filter applied at the schema-importer level.
array
The list of table names. Also returned:
connection_id, connection_type, schema_name, total_returned, and pagination.discover_file_schema
Read-only. Cloud-storage or SFTP connections only. Detects the columns of a delimited file (CSV, TSV, and similar). The file-source equivalent ofdiscover_schema, which handles database connections only. Each call reads a sample of the actual file over the network, so use sparingly.
integer
required
A cloud-storage or SFTP connection id.
string
required
File path on the connection, for example
/data/customers.csv.string
default:","
Field delimiter. Use
\t for TSV.boolean
default:"true"
Whether the first row holds column names. When
true, the detected field names come from that header.integer
default:"20"
Sample size the importer reads. 1 to 200.
array
A flat, best-effort list of the detected column names. Use it to wire a Select.
array
The importer’s raw field objects, passed through unchanged, ready to copy into a source component’s
schema.fields. Also returned: connection_id, connection_type, path, and field_count.preview_data
Read-only. Database connections only. Returns column metadata plus a small sample of rows from a database table. Each call hits the schema-importer and the customer’s database, so use sparingly.integer
required
A database connection id from
list_connections.string
required
Table name to sample.
string
Schema the table lives in, when the database uses schemas (for example
public).integer
default:"20"
Rows to return. 1 to 200.
string
A single SQL filter fragment. Semicolons (
;) and comment markers (--, /*) are rejected as defense against multi-statement injection.array
Column metadata for the sampled table.
array
The sampled rows.
boolean
true when the table has more rows than were returned. Also returned: connection_id, connection_type, schema_name, table, requested_row_count, where_clause, and row_count_returned.preview_transformation
Read-only. Database-backed sources only (v1). Previews what a single component produces on sample data, mid-build, without a destination. It runs the source-through-target chain on a small sample of the real source data (the same engine the dashboard “preview” button uses), so it works before a pipeline is finished, unlikevalidate_package, which needs a complete graph. Components fed by SaaS, REST, or file sources return a clear “not yet supported” error.
integer
required
The package (job) id the component belongs to.
string
required
The inner
name of the component whose output you want to see.object
Overrides for package variables during this preview run, for example for parameterized sources.
string
The previewed component’s name.
array
The output columns, each
{ name, type }.array
A sample of the component’s output rows.
integer
Number of rows returned. A
message is included when the preview produced no rows.profile_data
Read-only. Database connections only. Profiles a table’s columns over a sample of rows so an agent can reason about data quality before designing a pipeline. Statistics are sample-based estimates (the leading N rows returned by the database, not a random sample), not full-table figures.integer
required
A database connection id.
string
required
Table to profile.
string
Schema the table lives in.
array
Restrict profiling to this subset of columns. Omit to profile all.
integer
default:"500"
Rows to sample. 1 to 2000.
string
A single SQL filter fragment.
;, --, and /* are rejected.array
Per column: type (inferred from sampled values), null %, approximate distinct count, min/max/mean (numeric), most common values, and quality flags (
all_null, high_null, constant, unique).integer
How many rows the sample actually contained. Also returned:
connection_id, schema_name, table, and note (a reminder that the statistics are estimates).test_connection
Read-only from Integrate.io’s side (no state is persisted), but it does ping the customer’s upstream system. Actively tests a connection to verify reachability and authentication, returning success or failure with the upstream error message. Failed tests can produce upstream side effects (audit log entries, rare account lockouts on bad credentials), so use it sparingly, typically once after a user reports a connection problem, not as a repeated health check.integer
required
The connection id to test.
string
Short name (for example
postgres, s3) or STI class name. Disambiguates when the same integer id exists across the database and cloud-storage tables. Without it, the database row wins on collision.boolean
true if the connection was reachable and authenticated.string
The upstream error message on failure, so the agent can suggest a specific next step (re-auth, host/port fix, and so on).
integer
How long the test took, in milliseconds. Also returned:
connection_id and connection_type.Documentation
ask_docs
Read-only. Returns public documentation, no account data. Asks the live Integrate.io ETL & Reverse ETL documentation a question and returns an answer grounded in the docs plus source links. Consult it before guessing about component configuration, connector setup, expression functions, write modes, variables, scheduling, or clusters. Each call hits the external Mintlify API.string
required
Your question. Max 2000 characters.
string
The grounded answer.
array
Supporting doc links, each
{ url, title }.