Flows
Flows orchestrate how data moves between systems. A flow chains one or more page generators (exports that produce records) into a pipeline of page processors (lookups and imports), with optional routers for conditional branching. Flows run on a cron schedule, on demand, or in response to real-time events, and expose endpoints for running, monitoring, and managing per-step errors.
Flow schema
Returns all flows in the account.
Filter to instance flows that inherit from this abstract (multi-instance) flow.
Filter to flows matching this exact external identifier.
Filter by name — a substring match, not an exact match. An empty value is ignored.
OrderFilter by the disabled flag.
Filter to flows belonging to this integration.
Sort order for the results. lastExecutedAt sorts by most recent
execution first, with never-run flows at the tail. The sort key is
updated when a run starts, so a long-running flow can appear lower
than one that started more recently.
When true, instance flows generated from abstract (multi-instance) flows are included in the results, which otherwise list only regular and abstract flows.
Maximum number of flows to return per page.
Opaque cursor for forward pagination. Pass the value from the Link
response header (rel="next") to fetch the next page.
Comma-separated list of fields to project into each returned record.
Triggers summary projection: the response contains a minimal identity
set (_id, name, plus resource-specific fields) with the requested
fields added on top. Supports dot notation for nested fields.
Mutually exclusive with exclude.
_integrationId,disabled,lastModifiedComma-separated list of fields to strip from the default response.
Unlike include, does not trigger summary projection — returns the
full record with the named fields removed. Protected identity fields
(e.g. name) cannot be stripped. Mutually exclusive with include.
createdAt,lastModifiedSuccessfully retrieved list of flows.
No flows exist in the account.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
GET /v1/flows HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"_id": "650b1a461bedf477d54f2e43",
"name": "Accounts: HubSpot to NetSuite",
"disabled": false,
"schedule": "? */5 * * * *",
"_integrationId": "64ff52dbf16aa23918259206",
"createdAt": "2023-09-20T16:13:58.339Z",
"lastModified": "2026-01-21T07:04:37.930Z",
"autoResolveMatchingTraceKeys": true,
"logging": {
"mode": "accountLevel"
}
},
{
"_id": "69f4b2cb95ec28be9ca1a88d",
"name": "Order Sync (paused)",
"disabled": true,
"createdAt": "2026-05-01T14:03:55.827Z",
"lastModified": "2026-05-01T14:03:56.179Z",
"logging": {
"mode": "accountLevel"
}
}
]Creates a new flow. Flows are created enabled (disabled: false) by default — set disabled: true on create if the flow is not ready to run.
At minimum, provide name and _integrationId. Do not leave the flow enabled with a schedule unless it is fully configured — it will start executing on schedule. For abstract/instance patterns, create the abstract flow first, then create instances with _abstractFlowId.
When _integrationId is omitted, the flow is auto-assigned to the account's "Standalone flows" integration rather than left standalone. If that migration integration does not exist on the account, the request fails with 422 standalone_flows_not_supported. Always pass an explicit _integrationId.
Fields for creating or updating a flow.
Use pageProcessors for simple linear flows or routers for conditional branching — never
include both. The schedule field uses Celigo's 6-field cron format (not standard 5-field).
Display name for the flow.
Salesforce to NetSuite Customer SyncFree-text description of the flow's purpose.
Synchronizes customer records from Salesforce to NetSuite every 15 minutesIntegration this flow belongs to. Omitting it on create no longer
produces a standalone flow — the flow is auto-assigned to the
account's "Standalone flows" integration (or the create fails with
422 standalone_flows_not_supported when that integration is
missing). Always set it explicitly.
60a2c4e6f321d800129a1a3cCeligo 6-field cron expression: ? minute hour day-of-month month day-of-week.
Explicit minute/hour lists, ranges, wildcards, and step forms (*/N) are all valid.
Leave empty for event-driven or webhook-triggered flows.
? 5 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23 ? * *IANA timezone for the schedule (e.g. America/New_York). Defaults to UTC.
America/New_YorkWhen true, scheduled executions are suspended and the flow cannot be triggered. Running jobs are allowed to complete.
falseExample: trueSource export of a simple (single source, single destination) flow — the legacy
pre-flow-builder model still produced by Data Loader flows. Paired with _importId
instead of pageGenerators/pageProcessors; the server accepts and serves both
forms. Prefer pageGenerators for new flows.
60a2c4e6f321d800129a1a3cDestination import of a simple (single source, single destination) flow — the legacy
pre-flow-builder model still produced by Data Loader flows. Paired with _exportId
instead of pageGenerators/pageProcessors. Prefer pageProcessors for new flows.
60a2c4e6f321d800129a1a3cFlow IDs to trigger after this flow completes successfully. Accepts null as equivalent to an empty list (the server also serves null on documents saved that way).
["5f8d43a1b9e5a80011a35f2d","5f8d43a1b9e5a80011a35f2e"]External identifier for correlating the flow with a record in another system.
CUST-SYNC-001Tracks how far the user has progressed through the flow setup wizard in the UI.
donePossible values: When true, all page generators start simultaneously instead of sequentially.
trueWhen true, new errors with trace keys matching existing open errors are auto-resolved.
trueMarks this as an abstract (multi-instance) flow — a reusable template that cannot be
executed directly. Instance flows reference it via _abstractFlowId and provide overrides.
Constraints: top-level pageProcessors are not allowed (use routers), cannot reference
another abstract flow, cannot be a "run next" target, and cannot be unset while instances exist.
trueAbstract flow this instance inherits from. Immutable once set. The instance inherits
the flow graph and uses overrides to customize connections, schedules, and hooks.
60a2c4e6f321d800129a1a3cFlow grouping for organizing related flows in the UI. References an entry in the
integration's flowGroupings array (not a standalone collection); invalid ids are
silently dropped by the server. At runtime the flow's steps read the referenced
group's settings under the fixed scope key flowGrouping (e.g.
{{settings.flowGrouping.<fieldId>}}).
60a2c4e6f321d800129a1a3cCoordinates delta timing so this flow's checkpoint stays behind the referenced flow. Used for parent-child data relationships where the parent must sync first.
60a2c4e6f321d800129a1a3cLike _keepDeltaBehindFlowId but targets a specific export within a flow.
60a2c4e6f321d800129a1a3cWhen true, this flow is a draft that auto-deletes when its expiry passes
(draftExpiresAt in the response). Set at creation; an update can clear the
flag but never set it.
Flow created successfully.
Flow object as returned by the API.
Display name for the flow.
Salesforce to NetSuite Customer SyncFree-text description of the flow's purpose.
Synchronizes customer records from Salesforce to NetSuite every 15 minutesIntegration this flow belongs to. Omitting it on create no longer
produces a standalone flow — the flow is auto-assigned to the
account's "Standalone flows" integration (or the create fails with
422 standalone_flows_not_supported when that integration is
missing). Always set it explicitly.
60a2c4e6f321d800129a1a3cCeligo 6-field cron expression: ? minute hour day-of-month month day-of-week.
Explicit minute/hour lists, ranges, wildcards, and step forms (*/N) are all valid.
Leave empty for event-driven or webhook-triggered flows.
? 5 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23 ? * *IANA timezone for the schedule (e.g. America/New_York). Defaults to UTC.
America/New_YorkWhen true, scheduled executions are suspended and the flow cannot be triggered. Running jobs are allowed to complete.
falseExample: trueSource export of a simple (single source, single destination) flow — the legacy
pre-flow-builder model still produced by Data Loader flows. Paired with _importId
instead of pageGenerators/pageProcessors; the server accepts and serves both
forms. Prefer pageGenerators for new flows.
60a2c4e6f321d800129a1a3cDestination import of a simple (single source, single destination) flow — the legacy
pre-flow-builder model still produced by Data Loader flows. Paired with _exportId
instead of pageGenerators/pageProcessors. Prefer pageProcessors for new flows.
60a2c4e6f321d800129a1a3cFlow IDs to trigger after this flow completes successfully. Accepts null as equivalent to an empty list (the server also serves null on documents saved that way).
["5f8d43a1b9e5a80011a35f2d","5f8d43a1b9e5a80011a35f2e"]External identifier for correlating the flow with a record in another system.
CUST-SYNC-001Tracks how far the user has progressed through the flow setup wizard in the UI.
donePossible values: When true, all page generators start simultaneously instead of sequentially.
trueWhen true, new errors with trace keys matching existing open errors are auto-resolved.
trueMarks this as an abstract (multi-instance) flow — a reusable template that cannot be
executed directly. Instance flows reference it via _abstractFlowId and provide overrides.
Constraints: top-level pageProcessors are not allowed (use routers), cannot reference
another abstract flow, cannot be a "run next" target, and cannot be unset while instances exist.
trueAbstract flow this instance inherits from. Immutable once set. The instance inherits
the flow graph and uses overrides to customize connections, schedules, and hooks.
60a2c4e6f321d800129a1a3cFlow grouping for organizing related flows in the UI. References an entry in the
integration's flowGroupings array (not a standalone collection); invalid ids are
silently dropped by the server. At runtime the flow's steps read the referenced
group's settings under the fixed scope key flowGrouping (e.g.
{{settings.flowGrouping.<fieldId>}}).
60a2c4e6f321d800129a1a3cCoordinates delta timing so this flow's checkpoint stays behind the referenced flow. Used for parent-child data relationships where the parent must sync first.
60a2c4e6f321d800129a1a3cLike _keepDeltaBehindFlowId but targets a specific export within a flow.
60a2c4e6f321d800129a1a3cWhen true, this flow is a draft that auto-deletes when its expiry passes
(draftExpiresAt in the response). Set at creation; an update can clear the
flag but never set it.
Unique identifier for the resource. Format is a 24-character hexadecimal string.
5f8d43a1b9e5a80011a35f2cTimestamp when the resource was created. Set automatically and cannot be modified.
2023-04-01T09:15:32ZTimestamp when the resource was last updated. Changes whenever any property is modified.
2023-04-15T14:30:15ZTimestamp when the resource was soft-deleted. When null or absent, the resource is active.
2023-05-20T11:45:32ZWhen true, the flow is hidden from standard UI views but remains executable via API. Server-managed — ignored in POST and PUT bodies.
trueTimestamp when a draft flow auto-deletes. Server-computed when draft is set at
creation.
2026-01-15T09:30:00.000ZNumber of instance flows derived from this abstract flow.
3Integration App connector that owns this flow. Assigned by the connector
framework at install time — user creates that set it are rejected with 403
create_not_allowed.
60a2c4e6f321d800129a1a3cTimestamp of the flow's most recent execution. Absent until the flow has run at least once.
2023-04-15T09:15:00ZTimestamp when the flow's open errors were last resolved.
2023-04-14T16:45:00ZWhen true, the flow is free to run and does not require a paid subscription.
Template this flow was created from.
60a2c4e6f321d800129a1a3cSource resource this flow was cloned or installed from.
60a2c4e6f321d800129a1a3cBad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
POST /v1/flows HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 91
{
"name": "Salesforce to NetSuite Customer Sync",
"_integrationId": "64ff52dbf16aa23918259206"
}{
"_id": "650b1a461bedf477d54f2e43",
"name": "Accounts: HubSpot to NetSuite",
"disabled": false,
"schedule": "? 5 0,4,8,12,16,20 ? * *",
"timezone": "America/New_York",
"_integrationId": "64ff52dbf16aa23918259206",
"pageGenerators": [
{
"_exportId": "652583cf9085040ecbf54303"
}
],
"pageProcessors": [
{
"type": "import",
"_importId": "6508ab8b20b16404da729c64"
}
],
"autoResolveMatchingTraceKeys": true,
"logging": {
"mode": "accountLevel"
},
"createdAt": "2023-09-20T16:13:58.339Z",
"lastModified": "2023-09-20T16:13:58.412Z"
}Returns the complete configuration of a flow, including its page generators, processors, routers, schedule, and all nested settings.
Walk pageGenerators[]._exportId and pageProcessors[]._importId (or routers[].branches[].pageProcessors[]) to discover the exports and imports wired into the flow. For the full resource objects, use GET /v1/flows/{_id}/descendants instead of fetching each one individually. Instance flows (_abstractFlowId is set) have sparse top-level fields because the runtime merges them with the abstract flow's config.
Flow id.
5f8d43a1b9e5a80011a35f2cWhen true and the flow is an instance of an abstract (multi-instance) flow,
the response merges the abstract flow's configuration into the instance.
Without this, instance flows return a sparse object containing only
_abstractFlowId, overrides, and instance-level fields — no
pageGenerators or routers.
falseFlow retrieved successfully.
Flow object as returned by the API.
Display name for the flow.
Salesforce to NetSuite Customer SyncFree-text description of the flow's purpose.
Synchronizes customer records from Salesforce to NetSuite every 15 minutesIntegration this flow belongs to. Omitting it on create no longer
produces a standalone flow — the flow is auto-assigned to the
account's "Standalone flows" integration (or the create fails with
422 standalone_flows_not_supported when that integration is
missing). Always set it explicitly.
60a2c4e6f321d800129a1a3cCeligo 6-field cron expression: ? minute hour day-of-month month day-of-week.
Explicit minute/hour lists, ranges, wildcards, and step forms (*/N) are all valid.
Leave empty for event-driven or webhook-triggered flows.
? 5 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23 ? * *IANA timezone for the schedule (e.g. America/New_York). Defaults to UTC.
America/New_YorkWhen true, scheduled executions are suspended and the flow cannot be triggered. Running jobs are allowed to complete.
falseExample: trueSource export of a simple (single source, single destination) flow — the legacy
pre-flow-builder model still produced by Data Loader flows. Paired with _importId
instead of pageGenerators/pageProcessors; the server accepts and serves both
forms. Prefer pageGenerators for new flows.
60a2c4e6f321d800129a1a3cDestination import of a simple (single source, single destination) flow — the legacy
pre-flow-builder model still produced by Data Loader flows. Paired with _exportId
instead of pageGenerators/pageProcessors. Prefer pageProcessors for new flows.
60a2c4e6f321d800129a1a3cFlow IDs to trigger after this flow completes successfully. Accepts null as equivalent to an empty list (the server also serves null on documents saved that way).
["5f8d43a1b9e5a80011a35f2d","5f8d43a1b9e5a80011a35f2e"]External identifier for correlating the flow with a record in another system.
CUST-SYNC-001Tracks how far the user has progressed through the flow setup wizard in the UI.
donePossible values: When true, all page generators start simultaneously instead of sequentially.
trueWhen true, new errors with trace keys matching existing open errors are auto-resolved.
trueMarks this as an abstract (multi-instance) flow — a reusable template that cannot be
executed directly. Instance flows reference it via _abstractFlowId and provide overrides.
Constraints: top-level pageProcessors are not allowed (use routers), cannot reference
another abstract flow, cannot be a "run next" target, and cannot be unset while instances exist.
trueAbstract flow this instance inherits from. Immutable once set. The instance inherits
the flow graph and uses overrides to customize connections, schedules, and hooks.
60a2c4e6f321d800129a1a3cFlow grouping for organizing related flows in the UI. References an entry in the
integration's flowGroupings array (not a standalone collection); invalid ids are
silently dropped by the server. At runtime the flow's steps read the referenced
group's settings under the fixed scope key flowGrouping (e.g.
{{settings.flowGrouping.<fieldId>}}).
60a2c4e6f321d800129a1a3cCoordinates delta timing so this flow's checkpoint stays behind the referenced flow. Used for parent-child data relationships where the parent must sync first.
60a2c4e6f321d800129a1a3cLike _keepDeltaBehindFlowId but targets a specific export within a flow.
60a2c4e6f321d800129a1a3cWhen true, this flow is a draft that auto-deletes when its expiry passes
(draftExpiresAt in the response). Set at creation; an update can clear the
flag but never set it.
Unique identifier for the resource. Format is a 24-character hexadecimal string.
5f8d43a1b9e5a80011a35f2cTimestamp when the resource was created. Set automatically and cannot be modified.
2023-04-01T09:15:32ZTimestamp when the resource was last updated. Changes whenever any property is modified.
2023-04-15T14:30:15ZTimestamp when the resource was soft-deleted. When null or absent, the resource is active.
2023-05-20T11:45:32ZWhen true, the flow is hidden from standard UI views but remains executable via API. Server-managed — ignored in POST and PUT bodies.
trueTimestamp when a draft flow auto-deletes. Server-computed when draft is set at
creation.
2026-01-15T09:30:00.000ZNumber of instance flows derived from this abstract flow.
3Integration App connector that owns this flow. Assigned by the connector
framework at install time — user creates that set it are rejected with 403
create_not_allowed.
60a2c4e6f321d800129a1a3cTimestamp of the flow's most recent execution. Absent until the flow has run at least once.
2023-04-15T09:15:00ZTimestamp when the flow's open errors were last resolved.
2023-04-14T16:45:00ZWhen true, the flow is free to run and does not require a paid subscription.
Template this flow was created from.
60a2c4e6f321d800129a1a3cSource resource this flow was cloned or installed from.
60a2c4e6f321d800129a1a3cUnauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/flows/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"_id": "650b1a461bedf477d54f2e43",
"name": "Accounts: HubSpot to NetSuite",
"disabled": false,
"schedule": "? */5 * * * *",
"_integrationId": "64ff52dbf16aa23918259206",
"pageGenerators": [
{
"_exportId": "652583cf9085040ecbf54303"
}
],
"pageProcessors": [
{
"type": "import",
"_importId": "6508ab8b20b16404da729c64"
}
],
"autoResolveMatchingTraceKeys": true,
"logging": {
"mode": "accountLevel"
},
"createdAt": "2023-09-20T16:13:58.339Z",
"lastModified": "2026-01-21T07:04:37.930Z"
}Replaces the entire flow configuration. All fields not included in the request body are reset to defaults — this is a full replace, not a merge.
Always GET the flow first, modify the response, and PUT back — sending a partial body erases omitted fields. To change a single field (e.g. disabled, schedule), prefer PATCH over PUT. Read-only fields (_id, createdAt, lastModified) in the request body are silently ignored.
Flow id.
5f8d43a1b9e5a80011a35f2cFields for creating or updating a flow.
Use pageProcessors for simple linear flows or routers for conditional branching — never
include both. The schedule field uses Celigo's 6-field cron format (not standard 5-field).
Display name for the flow.
Salesforce to NetSuite Customer SyncFree-text description of the flow's purpose.
Synchronizes customer records from Salesforce to NetSuite every 15 minutesIntegration this flow belongs to. Omitting it on create no longer
produces a standalone flow — the flow is auto-assigned to the
account's "Standalone flows" integration (or the create fails with
422 standalone_flows_not_supported when that integration is
missing). Always set it explicitly.
60a2c4e6f321d800129a1a3cCeligo 6-field cron expression: ? minute hour day-of-month month day-of-week.
Explicit minute/hour lists, ranges, wildcards, and step forms (*/N) are all valid.
Leave empty for event-driven or webhook-triggered flows.
? 5 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23 ? * *IANA timezone for the schedule (e.g. America/New_York). Defaults to UTC.
America/New_YorkWhen true, scheduled executions are suspended and the flow cannot be triggered. Running jobs are allowed to complete.
falseExample: trueSource export of a simple (single source, single destination) flow — the legacy
pre-flow-builder model still produced by Data Loader flows. Paired with _importId
instead of pageGenerators/pageProcessors; the server accepts and serves both
forms. Prefer pageGenerators for new flows.
60a2c4e6f321d800129a1a3cDestination import of a simple (single source, single destination) flow — the legacy
pre-flow-builder model still produced by Data Loader flows. Paired with _exportId
instead of pageGenerators/pageProcessors. Prefer pageProcessors for new flows.
60a2c4e6f321d800129a1a3cFlow IDs to trigger after this flow completes successfully. Accepts null as equivalent to an empty list (the server also serves null on documents saved that way).
["5f8d43a1b9e5a80011a35f2d","5f8d43a1b9e5a80011a35f2e"]External identifier for correlating the flow with a record in another system.
CUST-SYNC-001Tracks how far the user has progressed through the flow setup wizard in the UI.
donePossible values: When true, all page generators start simultaneously instead of sequentially.
trueWhen true, new errors with trace keys matching existing open errors are auto-resolved.
trueMarks this as an abstract (multi-instance) flow — a reusable template that cannot be
executed directly. Instance flows reference it via _abstractFlowId and provide overrides.
Constraints: top-level pageProcessors are not allowed (use routers), cannot reference
another abstract flow, cannot be a "run next" target, and cannot be unset while instances exist.
trueAbstract flow this instance inherits from. Immutable once set. The instance inherits
the flow graph and uses overrides to customize connections, schedules, and hooks.
60a2c4e6f321d800129a1a3cFlow grouping for organizing related flows in the UI. References an entry in the
integration's flowGroupings array (not a standalone collection); invalid ids are
silently dropped by the server. At runtime the flow's steps read the referenced
group's settings under the fixed scope key flowGrouping (e.g.
{{settings.flowGrouping.<fieldId>}}).
60a2c4e6f321d800129a1a3cCoordinates delta timing so this flow's checkpoint stays behind the referenced flow. Used for parent-child data relationships where the parent must sync first.
60a2c4e6f321d800129a1a3cLike _keepDeltaBehindFlowId but targets a specific export within a flow.
60a2c4e6f321d800129a1a3cWhen true, this flow is a draft that auto-deletes when its expiry passes
(draftExpiresAt in the response). Set at creation; an update can clear the
flag but never set it.
Flow updated successfully.
Flow object as returned by the API.
Display name for the flow.
Salesforce to NetSuite Customer SyncFree-text description of the flow's purpose.
Synchronizes customer records from Salesforce to NetSuite every 15 minutesIntegration this flow belongs to. Omitting it on create no longer
produces a standalone flow — the flow is auto-assigned to the
account's "Standalone flows" integration (or the create fails with
422 standalone_flows_not_supported when that integration is
missing). Always set it explicitly.
60a2c4e6f321d800129a1a3cCeligo 6-field cron expression: ? minute hour day-of-month month day-of-week.
Explicit minute/hour lists, ranges, wildcards, and step forms (*/N) are all valid.
Leave empty for event-driven or webhook-triggered flows.
? 5 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23 ? * *IANA timezone for the schedule (e.g. America/New_York). Defaults to UTC.
America/New_YorkWhen true, scheduled executions are suspended and the flow cannot be triggered. Running jobs are allowed to complete.
falseExample: trueSource export of a simple (single source, single destination) flow — the legacy
pre-flow-builder model still produced by Data Loader flows. Paired with _importId
instead of pageGenerators/pageProcessors; the server accepts and serves both
forms. Prefer pageGenerators for new flows.
60a2c4e6f321d800129a1a3cDestination import of a simple (single source, single destination) flow — the legacy
pre-flow-builder model still produced by Data Loader flows. Paired with _exportId
instead of pageGenerators/pageProcessors. Prefer pageProcessors for new flows.
60a2c4e6f321d800129a1a3cFlow IDs to trigger after this flow completes successfully. Accepts null as equivalent to an empty list (the server also serves null on documents saved that way).
["5f8d43a1b9e5a80011a35f2d","5f8d43a1b9e5a80011a35f2e"]External identifier for correlating the flow with a record in another system.
CUST-SYNC-001Tracks how far the user has progressed through the flow setup wizard in the UI.
donePossible values: When true, all page generators start simultaneously instead of sequentially.
trueWhen true, new errors with trace keys matching existing open errors are auto-resolved.
trueMarks this as an abstract (multi-instance) flow — a reusable template that cannot be
executed directly. Instance flows reference it via _abstractFlowId and provide overrides.
Constraints: top-level pageProcessors are not allowed (use routers), cannot reference
another abstract flow, cannot be a "run next" target, and cannot be unset while instances exist.
trueAbstract flow this instance inherits from. Immutable once set. The instance inherits
the flow graph and uses overrides to customize connections, schedules, and hooks.
60a2c4e6f321d800129a1a3cFlow grouping for organizing related flows in the UI. References an entry in the
integration's flowGroupings array (not a standalone collection); invalid ids are
silently dropped by the server. At runtime the flow's steps read the referenced
group's settings under the fixed scope key flowGrouping (e.g.
{{settings.flowGrouping.<fieldId>}}).
60a2c4e6f321d800129a1a3cCoordinates delta timing so this flow's checkpoint stays behind the referenced flow. Used for parent-child data relationships where the parent must sync first.
60a2c4e6f321d800129a1a3cLike _keepDeltaBehindFlowId but targets a specific export within a flow.
60a2c4e6f321d800129a1a3cWhen true, this flow is a draft that auto-deletes when its expiry passes
(draftExpiresAt in the response). Set at creation; an update can clear the
flag but never set it.
Unique identifier for the resource. Format is a 24-character hexadecimal string.
5f8d43a1b9e5a80011a35f2cTimestamp when the resource was created. Set automatically and cannot be modified.
2023-04-01T09:15:32ZTimestamp when the resource was last updated. Changes whenever any property is modified.
2023-04-15T14:30:15ZTimestamp when the resource was soft-deleted. When null or absent, the resource is active.
2023-05-20T11:45:32ZWhen true, the flow is hidden from standard UI views but remains executable via API. Server-managed — ignored in POST and PUT bodies.
trueTimestamp when a draft flow auto-deletes. Server-computed when draft is set at
creation.
2026-01-15T09:30:00.000ZNumber of instance flows derived from this abstract flow.
3Integration App connector that owns this flow. Assigned by the connector
framework at install time — user creates that set it are rejected with 403
create_not_allowed.
60a2c4e6f321d800129a1a3cTimestamp of the flow's most recent execution. Absent until the flow has run at least once.
2023-04-15T09:15:00ZTimestamp when the flow's open errors were last resolved.
2023-04-14T16:45:00ZWhen true, the flow is free to run and does not require a paid subscription.
Template this flow was created from.
60a2c4e6f321d800129a1a3cSource resource this flow was cloned or installed from.
60a2c4e6f321d800129a1a3cBad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
PUT /v1/flows/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 305
{
"name": "Accounts: HubSpot to NetSuite",
"_integrationId": "64ff52dbf16aa23918259206",
"disabled": false,
"schedule": "? 5 0,4,8,12,16,20 ? * *",
"timezone": "America/New_York",
"pageGenerators": [
{
"_exportId": "652583cf9085040ecbf54303"
}
],
"pageProcessors": [
{
"type": "import",
"_importId": "6508ab8b20b16404da729c64"
}
]
}{
"_id": "650b1a461bedf477d54f2e43",
"name": "Accounts: HubSpot to NetSuite",
"disabled": false,
"schedule": "? 5 0,4,8,12,16,20 ? * *",
"timezone": "America/New_York",
"_integrationId": "64ff52dbf16aa23918259206",
"pageGenerators": [
{
"_exportId": "652583cf9085040ecbf54303"
}
],
"pageProcessors": [
{
"type": "import",
"_importId": "6508ab8b20b16404da729c64"
}
],
"autoResolveMatchingTraceKeys": true,
"logging": {
"mode": "accountLevel"
},
"createdAt": "2023-09-20T16:13:58.339Z",
"lastModified": "2026-01-21T07:04:37.930Z"
}Deletes a flow. Soft-deleted and retained in the recycle bin for 30 days. Scheduled executions are stopped and any running jobs are cancelled.
Check GET /v1/flows/{_id}/dependencies first — if other resources reference this flow, the delete is blocked. Soft-deleted flows can be restored via the recycle bin endpoints within 30 days.
Flow id.
5f8d43a1b9e5a80011a35f2cFlow deleted successfully.
No content
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
The resource has dependents that must be deleted first. Each entry
in the errors array names one blocking resource.
DELETE /v1/flows/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Partially updates a flow using a JSON Patch document (RFC 6902). Only the replace operation is supported, and only on the following whitelisted paths:
/name
Flow display name
/description
Flow description
/disabled
Enable or disable the flow
/logging/debugUntil
Debug logging expiry (ISO-8601; the maximum window is license-dependent — 72 hours on standard licenses, 422 beyond the cap)
/logging/mode
Logging mode
/runPageGeneratorsInParallel
Run page generators in parallel
/aiDescription
AI-generated description object
/schedule/frequency
Schedule frequency
/schedule/startDate
Schedule start date
/schedule/endDate
Schedule end date
/schedule/days
Schedule days
/schedule/cron
Cron expression
All other paths are rejected with 422.
PATCH is safer than PUT for toggling disabled or arming debug logging because it won't accidentally reset other fields. To arm debug logging, replace /logging/debugUntil with a future ISO timestamp (up to your license's cap — 72 hours on standard licenses); to disarm, set it to a past timestamp or null.
Flow id.
5f8d43a1b9e5a80011a35f2cA JSON Patch document (RFC 6902). Send an array of patch operations on whitelisted fields — all other paths are rejected with 422.
The operation to perform.
JSON Pointer (RFC 6901) to the field to patch. Only
whitelisted paths are accepted — unlisted paths return
422 with "<path> is not a whitelisted property".
The new value to set. Required for replace and add, omit for remove.
Flow patched successfully.
No content
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
PATCH /v1/flows/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 50
[
{
"op": "replace",
"path": "/disabled",
"value": true
}
]No content
Creates a copy of a flow along with all transitive dependencies (exports, imports, scripts). _integrationId is required, and connectionMap is required when the flow references connections — map a connection id to itself to reuse it, or to a different id to remap.
Use GET /v1/flows/{_id}/clone/preview first to see what resources will be created and which connections need remapping. The cloned flow is always created disabled: true.
Flow id to clone.
5f8d43a1b9e5a80011a35f2cRequest body for cloning a flow.
Optional name for the cloned resource. If omitted, the server may generate a default clone name.
Clone - Account FlowIntegration to attach the cloned flow to. The server rejects clones without it
(invalid_ref "Integration not found for the given id").
69680d5c6377215a7165d21bFlow cloned successfully. Returns a manifest of the resources the clone created.
Response body for a clone operation. Some clone endpoints return the cloned resource, while others may return a list of related created resources.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
POST /v1/flows/{_id}/clone HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 146
{
"name": "__golden_flow_clone",
"_integrationId": "6a28d8c4ff0bf912de528405",
"connectionMap": {
"6a28d883c2cd3271c871ee48": "6a28d883c2cd3271c871ee48"
}
}[
{
"model": "Import",
"_id": "69e9953d7a8373d88147b5ec"
},
{
"model": "Export",
"_id": "69e9953608de3c480cbb1a09"
},
{
"model": "Flow",
"_id": "69e99544f3a2ac489d0f7953"
}
]Returns a preview of resources that would be created by cloning this flow — the target flow and all transitive dependencies (connections, exports, imports, scripts, async helpers, lookup caches). No resources are created.
Call this before POST /v1/flows/{_id}/clone to discover which connections need remapping in the connectionMap body field.
Flow id to preview cloning.
5f8d43a1b9e5a80011a35f2cClone preview retrieved successfully.
Preview of the resources that would be created by a clone operation.
Each object in the objects array represents a resource that will be
cloned, including the target resource and all transitive dependencies
(connections, scripts, exports, imports, etc.).
Whether the clone requires a stack (connector-level) environment to proceed.
The stack id associated with the resource, or null if no stack is involved.
5f8d43a1b9e5a80011a35f2cUnauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/flows/{_id}/clone/preview HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"objects": [
{
"model": "Flow",
"doc": {
"name": "Account Flow",
"disabled": true,
"pageGenerators": [
{
"_exportId": "69a9aa5d3b213b3ac975e8d2"
}
],
"pageProcessors": [
{
"type": "import",
"_importId": "69a9aa5d3b213b3ac975e8d3"
}
]
}
},
{
"model": "Export",
"doc": {
"name": "Get Modified Accounts",
"_connectionId": "69497fc261ff724066b79101"
}
},
{
"model": "Import",
"doc": {
"name": "Upsert Accounts",
"_connectionId": "69497fc261ff724066b79100"
}
}
],
"stackRequired": false,
"_stackId": null
}Returns the full resource objects for every import, export, and tool referenced by the flow. This is a convenience endpoint that resolves the flow's entire dependency tree in a single call — equivalent to reading the flow config and then fetching each referenced resource individually, but without the N+1 round-trips.
The returned arrays mirror the full resource shapes from GET /v1/imports/{_id}, GET /v1/exports/{_id}, and GET /v1/tools/{_id}.
Flow id.
The flow's descendant resources.
The full resource objects for every import, export, and tool referenced by the flow. Useful for fetching a flow's entire dependency tree in a single call instead of resolving each resource individually.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/flows/{_id}/descendants HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"imports": [
{
"_id": "69a9aa5d3b213b3ac975e8d3",
"name": "Upsert Accounts",
"_connectionId": "69497fc261ff724066b79100"
}
],
"exports": [
{
"_id": "69a9aa5d3b213b3ac975e8d2",
"name": "Get Modified Accounts",
"_connectionId": "69497fc261ff724066b79101"
}
],
"tools": []
}Returns a per-step count of currently open (unresolved) errors for the flow. Each entry carries the step id and its open-error count; entries with zero errors still appear so the caller sees the full step roster.
For the full list of error records on a single step, call GET /v1/flows/{_id}/{_stepId}/errors. For a whole-integration rollup, use GET /v1/integrations/{_id}/errors. lastErrorAt is only populated on entries with numError > 0.
Flow id.
Per-step open-error summary.
Per-step summary of open errors for a flow. One entry per export or import step; entries with
numError: 0 still appear so the caller can see the full step list.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/flows/{_id}/errors HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"flowErrors": [
{
"_expOrImpId": "69a9aa5d3b213b3ac975e8d2",
"numError": 3,
"lastErrorAt": "2026-04-21T10:51:13.221Z"
},
{
"_expOrImpId": "69a9aa5c54e3d9bd11b86d82",
"numError": 0
}
]
}Replaces every occurrence of one connection with another across all exports, imports, and lookups in the flow. This is the recommended way to swap connections during environment promotion (e.g. credential rotation) — it updates all references atomically instead of requiring per-resource PUTs.
The replacement connection must exist and be of the same adaptor type as the original. If the types do not match, the request is rejected with a 422.
Use GET /v1/flows/{_id}/descendants to verify which resources use a given connection before replacing.
Flow id.
Request body to replace one connection with another across all exports, imports, and lookups in a flow. Both the current and replacement connection ids are required. The replacement connection must exist and be of the same adaptor type as the original.
The id of the connection currently used by the flow's resources.
5f7c579b6411271af4e7cefaThe id of the replacement connection to swap in.
5f7c579b6411271af4e7cefbConnection replaced successfully across all flow resources. No response body.
No content
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
PUT /v1/flows/{_id}/replaceConnection HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 90
{
"_connectionId": "69497fc261ff724066b79100",
"_newConnectionId": "69680d5c6377215a7165d301"
}No content
Queues an on-demand run of the flow and returns the parent job id. The run is asynchronous: the response returns as soon as the job is queued; use GET /v1/jobs/{_id} (with the returned _jobId) or GET /v1/flows/{_id}/jobs/latest to poll for terminal status.
The request body is optional. When omitted, the flow runs with its configured schedule behavior — for delta flows this means using the current lastExportDateTime as the lower bound. Pass export.startDate / export.endDate to override the delta window for this run only (the flow's checkpoint still advances on success). Pass _exportIds to limit execution to a subset of the flow's generators (useful for flows with many independent sources).
Flow-level preconditions enforced by the platform:
The flow must not be
disabled.The flow must be in an enabled integration (when part of one).
To trace a run end-to-end, arm debug logging before calling this, then use the returned _jobId with the execution-log endpoints. For delta backfills, prefer passing explicit startDate/endDate over editing the export's lastExportDateTime — the override is scoped to one run. A 200 with _jobId absent means the request was accepted but no job was queued, usually because another run is already in progress.
Flow id.
Optional overrides for a manual flow run. Omit the body (or send {}) to run the flow with its default
configuration.
Optional subset of exports (page generators) to run. Omit to run every generator on the flow. Useful for multi-generator flows where only one source needs re-pulling.
Flow run accepted and queued.
Response from POST /v1/flows/{_id}/run. Shape varies by run type:
- Single queued run — an object with the parent job id (
_jobId) plus queue metadata. - On-demand / multi-export run — an array of per-export run records.
- Rejected run — an object with an
errorfield. (Note: a run on a disabled flow is rejected with HTTP 422invalid_flow, not this shape.)
Callers should branch on the response shape before treating it as a single job.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
POST /v1/flows/{_id}/run HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2
{}{
"_jobId": "69f4144a3a4b314bd6dc600d",
"_exportId": "652583cf9085040ecbf54303",
"endDate": "2026-06-09T18:30:00.000Z",
"queueName": "flow-runner",
"message": "{\"_jobId\":\"69f4144a3a4b314bd6dc600d\",\"_exportId\":\"652583cf9085040ecbf54303\"}"
}Returns the trace-key pattern for each page generator in the flow. Trace keys are used to correlate source records with their downstream results in execution logs — they let you look up "what happened to record X" without scanning the full log.
Each entry in the returned array corresponds to one page generator (pgIndex matches the zero-based position in the flow's pageGenerators array). The traceKeyPattern describes which source-record fields and/or Handlebars templates are combined to produce the key.
If both fields and templates are empty for a generator, the flow has no trace key configured and log correlation must be done by position or other means. Trace keys are especially important for fan-out flows where one source record produces many destination records.
Flow id.
Trace-key patterns for each page generator in the flow.
One entry per page generator in the flow. Each entry describes the trace-key pattern used to correlate source records with their downstream results in execution logs.
Zero-based index of the page generator in the flow's pageGenerators array.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/flows/{_id}/traceKey HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"pgIndex": 0,
"traceKeyPattern": {
"fields": [
"internalid"
],
"templates": []
}
}
]Returns the flow-level "last export date/time" checkpoint — the most recent export timestamp across all generators (exports) in the flow. This value is what gets substituted into the {{lastExportDateTime}} Handlebars variable on the next delta run of any export in the flow.
The checkpoint advances automatically at the end of a successful delta run. It can be overridden per run by passing export.startDate / export.endDate to POST /v1/flows/{_id}/run.
A missing or very old value means the next delta run will re-scan the full history window from the source. This is the flow-scoped checkpoint; per-export checkpoints (for flows with multiple generators that advance independently) are exposed on the export record's delta block.
Flow id.
The flow's current delta checkpoint.
The flow's delta checkpoint — the most recent export timestamp across all page generators in the flow.
Used by delta-export logic to compute the next {{lastExportDateTime}} value.
ISO-8601 timestamp. null if the flow has never produced an export.
2026-01-15T09:30:00.000ZUnauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/flows/{_id}/lastExportDateTime HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"lastExportDateTime": "2026-04-23T02:50:47.961Z"
}Assigns one or more flows to a flow-grouping (section) within their integration. This is the collection-level endpoint used by the UI's "move to section" action — it updates multiple flows in a single call rather than requiring a per-flow PUT /v1/flows/{_id} with a modified _flowGroupingId.
The flows referenced in _flowIds must all belong to the same integration as the target _flowGroupingId. Pass _flowGroupingId: null (or an empty string, depending on platform version) to remove the flows from their current group back to the integration's default section.
Flow groupings are managed on the parent integration (PUT /v1/integrations/{_id} with a modified flowGroupings[] array) — create the group first, then call this to populate it.
Assign one or more flows to a flow group inside their parent integration. Replaces each flow's current grouping membership; there is no multi-group membership model.
The flows to move. All must belong to the same integration as the target flow group.
Id of the flow group (within the integration's flowGroupings[]). Pass null (or an empty
string, depending on platform version) to remove the flows from their current group back to the
integration's default section.
Flows reassigned. Empty response body. The server does not validate the grouping id —
nonexistent _flowGroupingId values are also accepted with 204.
No content
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
PUT /v1/flows/updateFlowGrouping HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 113
{
"_flowIds": [
"69497fc443fc1f9a03d31bd9",
"69497fc443fc1f9a03d31bda"
],
"_flowGroupingId": "66d9f7124ae2ff995b253374"
}No content
Returns one page of currently-open (unresolved) errors for a single step (export or import) within a flow. The step id is the _exportId / _importId from the flow's pageGenerators[], pageProcessors[], or routers[].branches[].pageProcessors[].
For a flow-wide rollup (per-step counts only), use GET /v1/flows/{_id}/errors instead. To scope the list to one specific run, pass _flowJobId together with the required occurredAt_gte. Errors with a retryDataKey are retryable via POST .../retry; connection-level errors typically lack one and require a full flow rerun to recover.
Flow id.
Export or import id — the step within the flow.
Only return errors produced by this flow-run job (each error record carries its
_flowJobId). Must be paired with occurredAt_gte — without it the request fails with
400 invalid_flowjobid_param.
Only return errors that occurred at or after this instant (inclusive). Required whenever
_flowJobId is supplied; usable on its own to bound the window.
Only return errors that occurred at or before this instant (inclusive). Optional even when
filtering by _flowJobId; combine with occurredAt_gte to select a window.
Only return errors carrying at least one of the listed tags. Repeat the parameter once per
value (?tags=ShHjr&tags=untagged); values are the account's short tagId codes from
GET /v1/tags, not the tag names shown in each error's tags array — unknown values
(including comma-joined lists) fail with 400 invalid_tagid_param. The literal value
untagged matches errors with no tags and can be mixed with real tag ids.
One page of open errors on this step.
One page of open errors for a flow step. Body-paginated: when nextPageURL is present, follow it
to fetch the next page.
URL for the next page. Omitted entirely (not null) when there are no further pages.
Some clients strip a leading /api prefix before reissuing.
Invalid filter parameters. invalid_flowjobid_param — _flowJobId was supplied without
occurredAt_gte. invalid_ref — _flowJobId is not a valid object id. invalid_tagid_param —
a tags value is not a known tag id (or untagged).
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/flows/{_id}/{_stepId}/errors HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"errors": [
{
"errorId": "4694681992",
"occurredAt": "2026-05-01T02:47:38.705Z",
"source": "application",
"code": "400",
"message": "{\"error\":\"invalid_grant\",\"error_description\":\"Token expired\"}",
"traceKey": "6917b858a6be8384d52de19b",
"oIndex": "0",
"_flowJobId": "69f4144a3a4b314bd6dc600d",
"reqAndResKey": "5480514741295-d50eb7df6f92492dbea7722a3e1a5ad3-401-GET-export",
"purgeAt": "1780195658705"
}
]
}Tags a batch of open errors with an assignee for triage workflows. The errors stay open — this does not resolve or retry them — they simply appear in the assignee's "my errors" view until another action moves them.
The email value is accepted verbatim and is not validated against the account's user list. Re-assigning the same batch to a different user overwrites the prior assignment. Use PUT .../errors/unassign to remove assignments entirely.
Flow id.
Export or import id.
Request body for PUT /v1/flows/{_id}/{_stepId}/errors/assign. Assigns a batch of open errors to a
user by email; the errors remain open but are tagged with the assignee for triage views.
Ids of open errors to assign. Obtain from GET /v1/flows/{_id}/{_stepId}/errors → each entry's
errorId. Platform caps batch size around ~1000; chunk larger sets client-side.
Email of the account user to assign the errors to. Must be a user who has access to the account; the API does not create users implicitly.
integrator@example.comErrors assigned. Body echoes which ids were affected.
Echo of which error records the mutation touched. Returned by PUT .../errors/assign.
Error ids that were affected by the mutation.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
PUT /v1/flows/{_id}/{_stepId}/errors/assign HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 67
{
"errorIds": [
"6044134138",
"6027562904"
],
"email": "user@example.com"
}{
"errorsToReturn": [
"6044134138"
]
}Removes the assignee from a batch of open errors. The errors remain open — this is the inverse of PUT .../errors/assign. Non-existent error ids are silently ignored (no error raised).
The response's errorsToReturn contains only ids that were actually unassigned — ids that were already unassigned or don't exist are omitted.
Flow id.
Export or import id.
Request body for PUT /v1/flows/{_id}/{_stepId}/errors/unassign. Removes the assignee from a
batch of open errors. Non-existent error ids are silently ignored.
Ids of open errors to unassign. Obtain from GET /v1/flows/{_id}/{_stepId}/errors → each
entry's errorId. Non-existent ids are silently ignored (no error raised).
Errors unassigned. Body echoes which ids were actually affected.
Response from PUT /v1/flows/{_id}/{_stepId}/errors/unassign. Echoes which error ids were
actually unassigned — ids that were not found or were already unassigned are omitted.
Error ids that were actually unassigned by this call.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
PUT /v1/flows/{_id}/{_stepId}/errors/unassign HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 40
{
"errorIds": [
"6044134138",
"6027562904"
]
}{
"errorsToReturn": [
"6044134138"
]
}Returns a pre-signed S3 URL that streams all currently-open errors for a flow step as a CSV file. The URL expires after approximately 15 minutes. The CSV always includes a header row, even when the step has zero open errors.
CSV columns: occurredAt, source, code, message, traceKey, exportDataURI, importDataURI, oIndex, retryDataKey, errorId, legacyId, reqAndResKey, purgeAt, tags, assignedTo, assignedBy, _assignedToUserId.
The signed URL requires no auth headers — do not attach your bearer token when fetching the CSV.
Flow id.
Export or import id — the step within the flow.
Resume from this error id — errors with ids lexically before this value are excluded from the CSV. Useful for incremental downloads.
Pre-signed S3 URL for the errors CSV.
Pre-signed S3 URL for downloading error or retry data as a CSV file. The URL expires after
approximately 15 minutes. Returned by the signedURL endpoints on errors, resolved errors,
and retry data.
Pre-signed S3 URL that streams a CSV file when fetched with a plain GET (no auth headers needed). Expires ~15 minutes after generation. The CSV always includes a header row, even when there are zero matching records.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/flows/{_id}/{_stepId}/errors/signedURL HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"signedURL": "https://celigo-error-downloads.s3.amazonaws.com/errors.csv?X-Amz-Expires=900&..."
}Returns one page of already-resolved errors for a flow step (same shape as the open-errors listing).
Errors arrive here either because a user marked them resolved (PUT .../resolved) or because a successful retry auto-resolved them. The platform retains resolved errors through the account's retention window; use DELETE .../resolved to purge them earlier.
resolvedBy distinguishes how each error was closed: auto means a system-initiated auto-retry cleared it; a user ID means the error was resolved manually or via a user-triggered retry.
Flow id.
Export or import id.
Only return resolved errors produced by this flow-run job. Must be paired with
resolvedAt_gte — without it the request fails with 400 invalid_flowjobid_param.
Only return errors that originally occurred at or after this instant (inclusive). Bounds
occurredAt (when the error happened), not resolvedAt (when it was closed).
Only return errors that originally occurred at or before this instant (inclusive).
Combine with occurredAt_gte to bound when the errors happened.
Only return errors resolved at or after this instant (inclusive). Required whenever
_flowJobId is supplied; usable on its own to bound the window.
Only return errors resolved at or before this instant (inclusive). Optional even when
filtering by _flowJobId; combine with resolvedAt_gte to select a window.
Only return resolved errors carrying at least one of the listed tags. Repeat the parameter
once per value (?tags=ShHjr&tags=untagged); values are the account's short tagId codes
from GET /v1/tags, not the tag names shown in each error's tags array — unknown values
fail with 400 invalid_tagid_param. The literal value untagged matches errors with no
tags and can be mixed with real tag ids.
Only return errors closed by the listed resolvers. Repeat the parameter once per value;
each value is a Mongo user id (matching the resolvedBy field on user-resolved errors).
The literal value auto matches platform-auto-resolved errors and can be mixed with
user ids (?resolvedBy=681a1c92c99fc39fabe2d7b9&resolvedBy=auto). Unknown values are
not rejected — they simply match nothing.
One page of resolved errors.
One page of resolved errors for a flow step. Resolved errors are retained for audit (and for
potential un-resolving, though that's not exposed as an API operation) until either a user deletes
them via DELETE .../resolved or the purge window expires.
URL for the next page. Omitted entirely (not null) when there are no further pages.
Invalid filter parameters. invalid_flowjobid_param — _flowJobId was supplied without
resolvedAt_gte. invalid_ref — _flowJobId is not a valid object id.
invalid_tagid_param — a tags value is not a known tag id (or untagged).
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/flows/{_id}/{_stepId}/resolved HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"resolved": [
{
"errorId": "4694681992",
"occurredAt": "2026-05-01T02:47:38.705Z",
"source": "application",
"code": "400",
"message": "{\"error\":\"invalid_grant\",\"error_description\":\"Token expired\"}",
"traceKey": "6917b858a6be8384d52de19b",
"oIndex": "0",
"_flowJobId": "69f4144a3a4b314bd6dc600d",
"reqAndResKey": "5480514741295-d50eb7df6f92492dbea7722a3e1a5ad3-401-GET-export",
"purgeAt": "1780195658705",
"resolvedBy": "auto"
}
]
}Moves a batch of currently-open errors to the resolved list. The underlying records are unchanged — no retry happens; this is purely an administrative state change used to clear the open-errors queue after a user has reviewed the failures and decided they're not actionable.
To actually re-run the failed records, use POST .../retry instead. The request body field is named errors (carrying error ids), not errorIds. To clear the whole open-error queue in one call without listing ids, send selectAll: true with a lastErrorAt high-water mark instead of errors.
Flow id.
Export or import id.
Request body for PUT /v1/flows/{_id}/{_stepId}/resolved. Marks a batch of currently-open errors
as resolved — they move from the errors list to the resolved list. Target the errors one of two
ways: list their ids in errors, or set selectAll: true with a lastErrorAt high-water mark to
resolve every open error on the step without enumerating ids. The id field is named errors (not
errorIds) for historical reasons; it carries error ids.
Ids of open errors to mark resolved. Obtain from GET /v1/flows/{_id}/{_stepId}/errors → each
entry's errorId. Required unless selectAll is true.
When true, resolves every open error on the step in a single call, no matter how many, instead
of an enumerated errors list — omit errors and supply lastErrorAt to bound the batch.
Inclusive high-water mark for selectAll: errors whose occurredAt is after this instant are
not resolved, so failures that arrive after you trigger the bulk resolve stay open. Set it to
the step's most recent error timestamp — the lastErrorAt returned by
GET /v1/flows/{_id}/errors. Required when selectAll is true (otherwise the request fails
with 422 lastErrorAt is required when selectAll is true.).
Errors resolved (no body).
No content
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
invalid_request — selectAll was true but lastErrorAt was omitted.
PUT /v1/flows/{_id}/{_stepId}/resolved HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 38
{
"errors": [
"6044134138",
"6027562904"
]
}No content
Permanently removes resolved error records from the account. Use when the retention window hasn't expired yet but you want to clear out the resolved list (e.g. after a one-time cleanup pass).
Only resolved errors can be deleted through this endpoint — open errors must be resolved first. This is destructive: the records and their associated HTTP request/response captures are permanently removed. The request body field is named errors (carrying error ids). To clear the whole resolved list without listing ids, send selectAll: true with a lastErrorAt high-water mark instead of errors — note that here lastErrorAt bounds each record's resolvedAt, not occurredAt.
Flow id.
Export or import id.
Request body for DELETE /v1/flows/{_id}/{_stepId}/resolved. Permanently deletes resolved errors
from the account. Target the errors one of two ways: list their ids in errors, or set
selectAll: true with a lastErrorAt high-water mark to delete every resolved error on the step
without enumerating ids. The id field is named errors (carries error ids) — this matches the
shape used by the resolve PUT.
Ids of resolved errors to delete. Obtain from GET /v1/flows/{_id}/{_stepId}/resolved → each
entry's errorId. Required unless selectAll is true.
When true, deletes every resolved error on the step instead of an enumerated errors list —
omit errors and supply lastErrorAt to bound the batch.
Inclusive high-water mark for selectAll. Unlike resolve/retry (which bound on occurredAt),
this bounds each resolved record's resolvedAt: records resolved after this instant are not
deleted. Required when selectAll is true (otherwise the request fails with 422
lastErrorAt is required when selectAll is true.).
Resolved errors deleted (no body).
No content
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
invalid_request — selectAll was true but lastErrorAt was omitted.
DELETE /v1/flows/{_id}/{_stepId}/resolved HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 25
{
"errors": [
"6044134138"
]
}No content
Returns a pre-signed S3 URL that streams all resolved errors for a flow step as a CSV file. The URL expires after approximately 15 minutes. The CSV always includes a header row, even when there are zero resolved errors.
The CSV includes the same columns as the open-errors signed URL, plus two prepended columns: resolvedAt and resolvedBy.
Full CSV columns: resolvedAt, resolvedBy, occurredAt, source, code, message, traceKey, exportDataURI, importDataURI, oIndex, retryDataKey, errorId, legacyId, reqAndResKey, purgeAt, tags, assignedTo, assignedBy, _assignedToUserId.
For currently-open errors, use GET .../errors/signedURL instead.
Flow id.
Export or import id.
Resume from this error id — errors with ids lexically before this value are excluded from the CSV.
Pre-signed S3 URL for the resolved errors CSV.
Pre-signed S3 URL for downloading error or retry data as a CSV file. The URL expires after
approximately 15 minutes. Returned by the signedURL endpoints on errors, resolved errors,
and retry data.
Pre-signed S3 URL that streams a CSV file when fetched with a plain GET (no auth headers needed). Expires ~15 minutes after generation. The CSV always includes a header row, even when there are zero matching records.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/flows/{_id}/{_stepId}/resolved/signedURL HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"signedURL": "https://celigo-error-downloads.s3.amazonaws.com/resolved.csv?X-Amz-Expires=900&..."
}Re-runs the per-record data snapshots captured when the listed errors occurred. A successful retry auto-resolves the underlying open-error record. A retry that fails again stays open (and may accumulate error history, depending on the adaptor).
Only errors that carry a retryDataKey can be retried — typically these are record-level errors from imports or transforms. Connection-level errors (classification: connection) don't have a retryDataKey; to recover from those, re-run the whole flow after fixing the connection.
Response behavior splits on whether anything matched:
At least one record matched — a supplied
retryDataKey, or (inselectAllmode) a retriable open error on or beforelastErrorAt→ 200 with atype: "retry"Job record (the queued retry job; poll it viaGET /v1/jobs/{_id}). A successful retry clears the original error fromGET .../errorsand moves it into/resolvedwithresolvedByset to the user who triggered the retry. System-initiated auto-retries setresolvedByto"auto"instead.Nothing matched → 204 silent no-op. There is no per-key validation: the endpoint does not 400 on bogus keys; callers must poll
GET .../errorsto confirm any change.
Retry outcome semantics. A retry that still fails generates a new error record with a new errorId (the original one is auto-resolved when the retry ultimately succeeds, or stays open pending next retry). Building a UI on top of this endpoint needs to reconcile the "before" and "after" error lists by retryDataKey, not errorId.
To modify a record before retrying, call GET .../{ retryDataKey}/data, mutate the payload, PUT it back, then call this endpoint. Retried records go through the same page-processor pipeline as new records with no ordering guarantees. To retry the whole open-error queue without listing keys, send selectAll: true with a lastErrorAt high-water mark instead of retryDataKeys — one call retries every matching error, no matter how many (errors without a retryDataKey are skipped).
Flow id.
Export or import id.
Request body for POST /v1/flows/{_id}/{_stepId}/retry. Re-runs the per-record data snapshot
captured at the moment each error occurred. A successful retry auto-resolves the underlying error.
Target the records one of two ways: list their snapshot keys in retryDataKeys, or set
selectAll: true with a lastErrorAt high-water mark to retry every retriable open error on the
step without enumerating keys.
Opaque per-error snapshot keys. Obtain from GET /v1/flows/{_id}/{_stepId}/errors →
retryDataKey on each entry that has one. Errors without a retryDataKey (typically
connection-level failures) cannot be retried via this endpoint — rerun the whole flow instead.
Required unless selectAll is true.
When true, retries every retriable open error on the step in a single call, no matter how many,
instead of an enumerated retryDataKeys list — omit retryDataKeys and supply lastErrorAt
to bound the batch. Open errors without a retryDataKey are skipped.
Inclusive high-water mark for selectAll: errors whose occurredAt is after this instant are
not retried, so failures that arrive after you trigger the bulk retry stay open. Set it to the
step's most recent error timestamp — the lastErrorAt returned by GET /v1/flows/{_id}/errors.
Required when selectAll is true (otherwise the request fails with 422
lastErrorAt is required when selectAll is true.).
Retry job queued. Body is the queued type: "retry" job record; poll it via
GET /v1/jobs/{_id} to observe the retry's outcome.
A job represents one execution of a flow/export/import (or a retry) in integrator.io. Jobs are read-only records created by the platform when executions occur.
Parent jobs (type: flow) carry aggregate counters; child jobs (type: export or import)
carry per-step counters -- do not sum both to avoid double-counting. _exportId on a parent
flow job references the page-generator export, not all exports in the flow.
Unique identifier for the resource. Format is a 24-character hexadecimal string.
5f8d43a1b9e5a80011a35f2cTimestamp when the resource was created. Set automatically and cannot be modified.
2023-04-01T09:15:32ZTimestamp when the resource was last updated. Changes whenever any property is modified.
2023-04-15T14:30:15ZTimestamp when the resource was soft-deleted. When null or absent, the resource is active.
2023-05-20T11:45:32ZJob type.
Current job status.
Integration id this job belongs to (if applicable).
6842261335b64c0bcb308e4fFlow id this job belongs to (if applicable).
69f54d6b7009ea11abad707aExport id. Present on child export jobs and also on parent flow jobs (where it references the first page-generator export).
69f54d6a3469e3f5597848a1Import id for import child jobs (if applicable).
69e9953d7a8373d88147b5ecThe export or import resource ID for this child job. Present on child
jobs (type: export or type: import) — check type to determine
whether this references an export or import resource.
69f54d6c1e7f3a22cc7848b2If this is a retry job, the original job id being retried.
69e9820a12e2a80e73166a8aParent flow job id (for child jobs).
69f54d6f47185f8c7a500597Owner user id for the job.
Parent job id (used for branched flows / hierarchy).
69f54d6f47185f8c7a500597Bulk retry parent job id (if applicable).
69e981ee18808f3e5ed1b2fdWhen execution started.
2026-05-02T01:03:43.640ZWhen execution ended.
2026-05-02T01:03:51.757ZWhen errors for the job were fully resolved (if applicable).
2026-05-02T02:15:00.000ZLast time the job executed work (may differ from createdAt/startedAt).
2026-05-02T01:03:51.757ZWhen the job should be purged from primary storage.
2026-06-01T01:03:43.577ZWhen the job's analytics data expires.
2026-06-01T01:03:43.577ZWho/what triggered the job (free-form string).
schedulerWho/what requested cancellation (free-form string).
userGroups multiple related jobs for a single flow execution.
70f3bd04a01142b29031e36ccff9242bTotal number of errors produced by the job (including resolved ones).
Use numOpenError for the count of currently unresolved errors.
10Number of unresolved errors (equivalent to numError - numResolved).
This is the value dashboards surface as "errors needing attention."
10Number of resolved errors.
Number of errors resolved by the adaptor.
Number of successful records/pages.
10Number of ignored records/pages.
Legacy field used by retry logic. May be deprecated.
Number of pages generated by an export/page generator.
10When true, all export pages have been generated.
Number of pages processed by downstream imports.
10Branch/router index for branched flows (if applicable).
When true, this job is eligible for retry.
Effective logging mode for this job, resolved from the flow's logging.mode
and the account-level logging preference. Common values: basic (default),
off, on, debug.
basicWhen true, indicates the last page-generator job in the sequence. Internal use only.
Number of errors selected for this retry job — whether
enumerated explicitly or matched by selectAll filters.
Specific to this endpoint's response; not stored on the
job record.
3Nothing was retried — silent no-op. In enumerated mode, none of the supplied retryDataKeys
matched a stored snapshot; in selectAll mode, no retriable open error occurred on or before
lastErrorAt. Poll GET .../errors to confirm state.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
Request could not be processed. inactive_flow — the flow is disabled; enable it before
retrying. invalid_request — selectAll was true but lastErrorAt was omitted.
POST /v1/flows/{_id}/{_stepId}/retry HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 117
{
"retryDataKeys": [
"5481349726779-8b77ed93d0e54adcb734f51cc70d3919",
"5481349726780-2c11aa44d0e54adcb734f51cc70d3920"
]
}{
"_id": "69e9958f815ae7eae3d9146b",
"type": "retry",
"_importId": "69e9953d7a8373d88147b5ec",
"_flowId": "69e99544f3a2ac489d0f7953",
"status": "queued",
"numSuccess": 0,
"numError": 0,
"numResolved": 0,
"numOpenError": 0,
"retryErrorCount": 3,
"createdAt": "2026-04-23T03:44:15.515Z",
"lastModified": "2026-04-23T03:44:15.532Z"
}Retry errored records with exponential back-off
Re-runs errored record snapshots using an exponential decay (back-off) strategy. Behaves like POST .../retry but schedules retries with increasing delays between attempts, reducing load on the target system during transient outages.
Response behavior splits on whether anything matched:
At least one record matched — a supplied
retryDataKey, or (inselectAllmode) a retriable open error on or beforelastErrorAt→ 200 with a fulltype: "retry"Job record.Nothing matched → 204 silent no-op.
The flow must be enabled (not disabled).
Prefer this over POST .../retry when errors are caused by rate-limiting or transient target-system issues. Only errors with a retryDataKey can be retried — connection-level errors lack one and require a full flow rerun to recover. To retry the whole open-error queue without listing keys, send selectAll: true with a lastErrorAt high-water mark instead of retryDataKeys.
Flow id.
Export or import id.
Request body for POST /v1/flows/{_id}/{_stepId}/retry_with_exponential_decay. Retries errored
records using an exponential back-off strategy. Returns a Job object when at least one key matched,
or 204 if none matched. Target the records one of two ways: list their snapshot keys in
retryDataKeys, or set selectAll: true with a lastErrorAt high-water mark to retry every
retriable open error on the step without enumerating keys.
Opaque per-error snapshot keys. Same format as POST .../retry. Only errors that carry a
retryDataKey can be retried. Required unless selectAll is true.
When true, retries every retriable open error on the step in a single call, no matter how many,
instead of an enumerated retryDataKeys list — omit retryDataKeys and supply lastErrorAt
to bound the batch. Open errors without a retryDataKey are skipped.
Inclusive high-water mark for selectAll: errors whose occurredAt is after this instant are
not retried. Set it to the step's most recent error timestamp — the lastErrorAt returned by
GET /v1/flows/{_id}/errors. Required when selectAll is true (otherwise the request fails
with 422 lastErrorAt is required when selectAll is true.).
Retry job queued with exponential back-off. Body is the queued type: "retry" job record;
poll it via GET /v1/jobs/{_id}.
A job represents one execution of a flow/export/import (or a retry) in integrator.io. Jobs are read-only records created by the platform when executions occur.
Parent jobs (type: flow) carry aggregate counters; child jobs (type: export or import)
carry per-step counters -- do not sum both to avoid double-counting. _exportId on a parent
flow job references the page-generator export, not all exports in the flow.
Unique identifier for the resource. Format is a 24-character hexadecimal string.
5f8d43a1b9e5a80011a35f2cTimestamp when the resource was created. Set automatically and cannot be modified.
2023-04-01T09:15:32ZTimestamp when the resource was last updated. Changes whenever any property is modified.
2023-04-15T14:30:15ZTimestamp when the resource was soft-deleted. When null or absent, the resource is active.
2023-05-20T11:45:32ZJob type.
Current job status.
Integration id this job belongs to (if applicable).
6842261335b64c0bcb308e4fFlow id this job belongs to (if applicable).
69f54d6b7009ea11abad707aExport id. Present on child export jobs and also on parent flow jobs (where it references the first page-generator export).
69f54d6a3469e3f5597848a1Import id for import child jobs (if applicable).
69e9953d7a8373d88147b5ecThe export or import resource ID for this child job. Present on child
jobs (type: export or type: import) — check type to determine
whether this references an export or import resource.
69f54d6c1e7f3a22cc7848b2If this is a retry job, the original job id being retried.
69e9820a12e2a80e73166a8aParent flow job id (for child jobs).
69f54d6f47185f8c7a500597Owner user id for the job.
Parent job id (used for branched flows / hierarchy).
69f54d6f47185f8c7a500597Bulk retry parent job id (if applicable).
69e981ee18808f3e5ed1b2fdWhen execution started.
2026-05-02T01:03:43.640ZWhen execution ended.
2026-05-02T01:03:51.757ZWhen errors for the job were fully resolved (if applicable).
2026-05-02T02:15:00.000ZLast time the job executed work (may differ from createdAt/startedAt).
2026-05-02T01:03:51.757ZWhen the job should be purged from primary storage.
2026-06-01T01:03:43.577ZWhen the job's analytics data expires.
2026-06-01T01:03:43.577ZWho/what triggered the job (free-form string).
schedulerWho/what requested cancellation (free-form string).
userGroups multiple related jobs for a single flow execution.
70f3bd04a01142b29031e36ccff9242bTotal number of errors produced by the job (including resolved ones).
Use numOpenError for the count of currently unresolved errors.
10Number of unresolved errors (equivalent to numError - numResolved).
This is the value dashboards surface as "errors needing attention."
10Number of resolved errors.
Number of errors resolved by the adaptor.
Number of successful records/pages.
10Number of ignored records/pages.
Legacy field used by retry logic. May be deprecated.
Number of pages generated by an export/page generator.
10When true, all export pages have been generated.
Number of pages processed by downstream imports.
10Branch/router index for branched flows (if applicable).
When true, this job is eligible for retry.
Effective logging mode for this job, resolved from the flow's logging.mode
and the account-level logging preference. Common values: basic (default),
off, on, debug.
basicWhen true, indicates the last page-generator job in the sequence. Internal use only.
Nothing was retried — silent no-op. In enumerated mode, none of the supplied retryDataKeys
matched a stored snapshot; in selectAll mode, no retriable open error occurred on or before
lastErrorAt.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
Request could not be processed. inactive_flow — the flow is disabled; enable it before
retrying. invalid_request — selectAll was true but lastErrorAt was omitted.
POST /v1/flows/{_id}/{_stepId}/retry_with_exponential_decay HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 117
{
"retryDataKeys": [
"5481349726779-8b77ed93d0e54adcb734f51cc70d3919",
"5481349726780-2c11aa44d0e54adcb734f51cc70d3920"
]
}{
"_id": "69e9958f815ae7eae3d9146b",
"type": "retry",
"_importId": "69e9953d7a8373d88147b5ec",
"_flowId": "69e99544f3a2ac489d0f7953",
"status": "queued",
"numSuccess": 0,
"numError": 0,
"numResolved": 0,
"numOpenError": 0,
"createdAt": "2026-04-23T03:44:15.515Z",
"lastModified": "2026-04-23T03:44:15.532Z"
}Returns the per-record snapshot the runtime captured at the moment of failure — the shape that POST .../retry re-feeds into the flow pipeline. The response is an envelope: data carries the adaptor-specific record payload; surrounding fields (stage, pgExportId, oneToMany, pathToMany, childIndex, traceKey) identify where in the pipeline the record was when it failed and how it's structured.
The data field shows exactly the payload the runtime tried to submit — compare it against the source system to pinpoint transformation drift. Use PUT .../{retryDataKey}/data to mutate the snapshot before retrying. Only errors with a retryDataKey expose this endpoint; connection-class errors are rejected with no_retrydata_found. The stage field indicates where the retry will resume: page_processor_import re-runs the import (most common), page_generator means the error was upstream of the processor.
Flow id.
Export or import id.
The retryDataKey from the error record.
The stored retry-data snapshot.
Envelope around a per-record snapshot captured at the moment an error occurred. Returned by
GET /v1/flows/{_id}/{_stepId}/{retryDataKey}/data and accepted (full-replace) by the PUT on the
same path.
The data field carries the actual record payload the runtime tried to submit — its shape is
adaptor-specific. The surrounding fields identify where in the pipeline the failure happened and
how the record was structured.
Echoes the path parameter.
5f8d43a1b9e5a80011a35f2d-rdk-0The opaque record payload. For HTTPImport errors this is the HTTP response the target system returned; for data-level failures it's the record as seen by the step. Shape varies by adaptor.
Pipeline stage where the record was when the error occurred.
importMappingExtractId of the page-generator export that originated this record.
60a2c4e6f321d800129a1a3cWhether the stored record represents a one-to-many expansion. When true, childIndex and
pathToMany locate the specific sub-record inside the parent payload.
JSON-path / dot-path into the parent payload naming the array of sub-records. Null on one-to-one records.
lineItemsZero-based index into the pathToMany array when oneToMany: true. Null on one-to-one records.
Trace identifier for cross-bubble stitching in execution logs. Populated when the source export
has a traceKeyTemplate configured.
ORD-100245Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
No snapshot exists for this key. Body: {"errors":[{"code":"no_retrydata_found","message":"No retry data found for the given retryDataKey."}]}.
GET /v1/flows/{_id}/{_stepId}/{retryDataKey}/data HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"retryDataKey": "3c53260c0d7748d59ba20af21a2ba531",
"stage": "page_processor_import",
"pgExportId": "69e9953608de3c480cbb1a09",
"oneToMany": false,
"pathToMany": null,
"childIndex": null,
"traceKey": null,
"data": {
"method": "GET",
"url": "https://httpbin.org/anything",
"headers": {
"Host": "httpbin.org"
},
"args": {}
}
}Full-replace of the stored per-record snapshot. The body becomes the new payload that POST .../retry will feed back into the pipeline. Same envelope shape as the matching GET — send the whole object (not just data), optionally mutated.
The typical workflow is: GET .../{retryDataKey}/data, mutate data locally, PUT the whole envelope back, then POST .../retry with the same retryDataKey. Send the complete envelope — omitted fields are lost, and retryDataKey, stage, pgExportId must match the original GET. Editing the snapshot does not clear the error; it stays open until a subsequent retry or manual resolve.
Flow id.
Export or import id.
The retryDataKey from the error record.
Envelope around a per-record snapshot captured at the moment an error occurred. Returned by
GET /v1/flows/{_id}/{_stepId}/{retryDataKey}/data and accepted (full-replace) by the PUT on the
same path.
The data field carries the actual record payload the runtime tried to submit — its shape is
adaptor-specific. The surrounding fields identify where in the pipeline the failure happened and
how the record was structured.
Echoes the path parameter.
5f8d43a1b9e5a80011a35f2d-rdk-0The opaque record payload. For HTTPImport errors this is the HTTP response the target system returned; for data-level failures it's the record as seen by the step. Shape varies by adaptor.
Pipeline stage where the record was when the error occurred.
importMappingExtractId of the page-generator export that originated this record.
60a2c4e6f321d800129a1a3cWhether the stored record represents a one-to-many expansion. When true, childIndex and
pathToMany locate the specific sub-record inside the parent payload.
JSON-path / dot-path into the parent payload naming the array of sub-records. Null on one-to-one records.
lineItemsZero-based index into the pathToMany array when oneToMany: true. Null on one-to-one records.
Trace identifier for cross-bubble stitching in execution logs. Populated when the source export
has a traceKeyTemplate configured.
ORD-100245Snapshot updated (no body).
No content
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
No snapshot exists for this key. Body: {"errors":[{"code":"no_retrydata_found","message":"No retry data found for the given retryDataKey."}]}.
PUT /v1/flows/{_id}/{_stepId}/{retryDataKey}/data HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 315
{
"retryDataKey": "3c53260c0d7748d59ba20af21a2ba531",
"stage": "page_processor_import",
"pgExportId": "69e9953608de3c480cbb1a09",
"oneToMany": false,
"pathToMany": null,
"childIndex": null,
"traceKey": null,
"data": {
"method": "GET",
"url": "https://httpbin.org/anything",
"headers": {
"Host": "httpbin.org"
},
"args": {
"validated": "true"
}
}
}No content
Get a signed URL to download file-type retry data
Returns a pre-signed S3 URL for downloading the raw retry data file associated with an error. This only works for file-type retry data (e.g. file-based exports/imports). For standard record-based retry data, use GET .../{ retryDataKey}/data instead.
File-based adaptors (FTP, S3, etc.) store retry data as files; record-based adaptors store JSON snapshots accessible via GET .../{ retryDataKey}/data instead. The signed URL requires no auth headers.
Flow id.
Export or import id.
The retryDataKey from the error record.
Pre-signed S3 URL for the retry data file.
Pre-signed S3 URL for downloading error or retry data as a CSV file. The URL expires after
approximately 15 minutes. Returned by the signedURL endpoints on errors, resolved errors,
and retry data.
Pre-signed S3 URL that streams a CSV file when fetched with a plain GET (no auth headers needed). Expires ~15 minutes after generation. The CSV always includes a header row, even when there are zero matching records.
The retry data for this key is not file-type. Use GET .../{ retryDataKey}/data for
standard record-based retry data. Error code: invalid_operation.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
No retry data found for the given key. Error code: no_retrydata_found.
GET /v1/flows/{_id}/{_stepId}/{retryDataKey}/signedURL HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"signedURL": "https://celigo-retry-data.s3.amazonaws.com/file.dat?X-Amz-Expires=900&..."
}Get the HTTP request/response for an errored record
Returns the decoded HTTP request and response the runtime captured at the moment an error occurred, looked up by the opaque reqAndResKey found on each error in GET .../errors.
Sensitive values are masked before storage — query-string credentials, Authorization headers, OAuth bearer tokens, and similar are rendered as ********. You cannot recover the original values from this endpoint.
The time and response.receivedAt fields are epoch milliseconds, useful for correlating with target-system logs. Not every error has a stored trace — record-level errors from non-HTTP adaptors (e.g. NetSuite distributed imports) lack a reqAndResKey.
Flow id.
Export or import id.
The reqAndResKey value from the error record.
Decoded request/response pair.
Decoded HTTP request / response pair captured for a flow-step error. Retrieved via
GET /v1/flows/{_id}/{_stepId}/requests/{reqAndResKey}. Sensitive query-string and header values
(credentials, access tokens) are masked with ******** before storage.
Echoes the reqAndResKey path parameter.
5f8d43a1b9e5a80011a35f2d-req-0Internal storage id for this request/response pair.
66a1f2c3b4d5e6f7a8b9c0d1Epoch milliseconds when this pair was stored.
1768470600000Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
The key did not match any stored trace (purged, expired, or never captured). Error code:
file_not_found; message: "We are unable to find the file for the given fileName."
Also returned when the flow or step id is unknown (code: invalid_ref).
GET /v1/flows/{_id}/{_stepId}/requests/{reqAndResKey} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"request": {
"method": "GET",
"url": "https://api.hubapi.com/crm/v3/objects/companies?after=851",
"headers": {
"authorization": "********",
"accept": "application/json"
}
},
"response": {
"statusCode": 401,
"headers": {
"content-type": "application/json"
},
"body": "{\"error\":\"invalid_grant\",\"error_description\":\"Token expired\"}",
"receivedAt": 1777603658705
},
"key": "5480514741295-d50eb7df6f92492dbea7722a3e1a5ad3-401-GET-export",
"id": "d50eb7df6f92492dbea7722a3e1a5ad3",
"time": 1777603658705
}Returns a paginated list of HTTP request/response trace metadata for a flow step, filtered by time window, status code, method, and/or pipeline stage. Each entry contains summary metadata — use GET .../requests/{reqAndResKey} to fetch the full decoded request/response pair for a specific trace.
Important: Time parameters (time_lte, time_gt) must be epoch milliseconds (integers), not ISO 8601 strings.
Use GET .../requests/{reqAndResKey} to drill into individual request/response bodies. statusCode is returned as a string, not an integer. For oversized bodies stored in S3, follow up with GET .../requests/{key}/files/signedURL.
Flow id.
Export or import id.
Upper bound of the time window (inclusive), as epoch milliseconds. Defaults to now if omitted.
Lower bound of the time window (exclusive), as epoch milliseconds.
Filter to traces with this HTTP status code (e.g. 403, 500).
Filter to traces with this HTTP method (e.g. GET, POST).
Filter to traces captured at this pipeline stage (e.g. export, import).
One page of request/response trace metadata.
Paginated list of stored HTTP request/response trace metadata for a flow step. Returned by
GET /v1/flows/{_id}/{_stepId}/requests. Follow nextPageURL for additional pages; each page
adjusts the time_lte window by 600000 ms (10 minutes).
Full URL for the next page of results, or null when there are no more pages. Each page
shifts time_lte backward by 600000 ms (10 minutes).
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
Time parameters were passed as ISO strings instead of epoch milliseconds. Error code:
invalid_or_missing_field.
GET /v1/flows/{_id}/{_stepId}/requests HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"requests": [
{
"key": "5482087700743-20ce2838e1994598a66b8e36338dad38-403-GET-export",
"time": 1746057600000,
"method": "GET",
"statusCode": "403",
"stage": "export"
}
],
"nextPageURL": null
}Permanently removes specific stored request+response pairs from the per-step trace cache. Despite the un-parameterized path, this is not a blanket purge — the request body must name the exact reqAndResKey values to delete (from the errors listing). After deletion, subsequent calls to GET .../requests/{reqAndResKey} for the deleted keys fail with file_not_found.
The live API requires Content-Type: application/json plus a non-empty keys[] array. A request with no body, {}, or {keys: []} rejects with 400 invalid_url / "keys is not valid.".
The underlying error record in GET .../errors remains after deletion, but its reqAndResKey pointer will dangle. There is no single "purge all" call — enumerate current errors and collect all reqAndResKey values to clear the full cache.
Flow id.
Export or import id.
Request body for DELETE /v1/flows/{_id}/{_stepId}/requests. Targets specific stored
request/response traces for deletion by their opaque reqAndResKey identifiers — this is not a
blanket-purge endpoint despite the un-parameterized path.
reqAndResKey values to delete, as listed on each error from GET /v1/flows/{_id}/{_stepId}/errors.
Empty array rejects with 400 (invalid_url / "keys is not valid"); to purge everything, enumerate
the current errors' keys and send them.
Per-key deletion result.
Result of DELETE /v1/flows/{_id}/{_stepId}/requests. Lists which requested keys were deleted and
any per-key errors the platform encountered.
Keys that were successfully deleted. Subset of the request's keys[].
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
Content-Type: application/json header is missing.
DELETE /v1/flows/{_id}/{_stepId}/requests HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 74
{
"keys": [
"5482087700743-20ce2838e1994598a66b8e36338dad38-403-GET-export"
]
}{
"deleted": [
"5482087700743-20ce2838e1994598a66b8e36338dad38-403-GET-export"
],
"errors": []
}Get a signed URL for an oversized request/response body
Returns a pre-signed S3 URL for downloading the full request or response body when it was too large to store inline in the trace record. Most request/response pairs have inline bodies accessible via GET .../requests/{reqAndResKey} — this endpoint is only needed for the subset where the body was offloaded to S3 due to size.
Call GET .../requests/{reqAndResKey} first. If request.body or response.body is truncated or missing, use this endpoint to fetch the full payload from S3.
Flow id.
Export or import id.
The reqAndResKey value from the request trace.
Pre-signed S3 URL for the oversized body file.
Pre-signed S3 URL for downloading error or retry data as a CSV file. The URL expires after
approximately 15 minutes. Returned by the signedURL endpoints on errors, resolved errors,
and retry data.
Pre-signed S3 URL that streams a CSV file when fetched with a plain GET (no auth headers needed). Expires ~15 minutes after generation. The CSV always includes a header row, even when there are zero matching records.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
The S3 file does not exist — it was purged or was never offloaded. Error code:
file_not_found.
The request/response pair has an inline body — there is no offloaded file to download.
Error code: missing_bodykey.
GET /v1/flows/{_id}/{_stepId}/requests/{key}/files/signedURL HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"signedURL": "https://celigo-request-bodies.s3.amazonaws.com/body.json?X-Amz-Expires=900&..."
}Full-replace per-error: for each (errorId, retryDataKey) in the body, the stored tag set is replaced with tagIds. Pass tagIds: [] to clear all tags from the listed errors.
Tags are account-scoped short codes (from GET /v1/tags) — not free-form strings. The tagId you send here is the short code (e.g. F3ZBQ), not the tag document's Mongo _id.
The errors batch uses short keys (id = errorId, rdk = retryDataKey) to minimize body size. Use rdk: "" for errors without a retryDataKey (connection-class errors). This endpoint replaces the full tag set per error — to add a tag without removing existing ones, merge client-side first.
Flow id.
Export or import id.
Request body for PUT /v1/flows/{_id}/{_stepId}/tags. Replaces the tag set on each listed error
with tagIds. Pass an empty tagIds array to clear all tags from the listed errors.
Short tag codes to apply. Obtain from GET /v1/tags — use the short tagId field (e.g.
F3ZBQ), not the Mongo _id. Pass [] to remove all tags from the listed errors.
At most 3 tag codes per error (platform-enforced).
Tags updated. Body echoes affected ids split by current state (open vs resolved).
Echo of which error records the tag mutation touched, split by their current state. Returned by
PUT /v1/flows/{_id}/{_stepId}/tags.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
PUT /v1/flows/{_id}/{_stepId}/tags HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 135
{
"errors": [
{
"id": "6044134138",
"rdk": ""
},
{
"id": "6027562904",
"rdk": "5481349726780-2c11aa44d0e54adcb734f51cc70d3920"
}
],
"tagIds": [
"F3ZBQ"
]
}{
"errorsToReturn": {
"errors": [
"6044134138"
],
"resolved": []
}
}Asynchronously deletes execution-log entries for the flow that fall within the specified time range. Returns 202 Accepted with an empty body — the deletion runs in the background.
Both startedAt and endAt are required query parameters and must be valid ISO 8601 datetime strings. startedAt must be strictly before endAt; the server returns 400 invalid_query_params otherwise.
This is a destructive, irreversible operation. The 202 response does not include a job id; there is no way to poll for completion.
Flow id.
Start of the time range (inclusive). ISO 8601 datetime. Must be before endAt.
End of the time range (inclusive). ISO 8601 datetime. Must be after startedAt.
Accepted — log deletion is running asynchronously.
No content
Missing or invalid query parameters. Returned when startedAt or endAt is absent, not a valid
ISO datetime, or when startedAt is not before endAt.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
DELETE /v1/flows/{_id}/logs?startedAt=2026-01-01T00%3A00%3A00.000Z&endAt=2026-01-01T00%3A00%3A00.000Z HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Cancels every currently running job for the specified flow. This is the flow-scoped equivalent of cancelling individual jobs via PUT /v1/jobs/{_id} — it finds all in-progress jobs for the flow and requests cancellation in a single call.
No request body is required. The response is an empty 204 on success.
Cancellation is asynchronous — jobs may take a few seconds to fully stop after the 204 is returned.
Flow id.
Cancellation requested for all running jobs. No response body.
No content
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
POST /v1/flows/{_id}/jobs/cancel HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Searches for flow-run jobs that contain records matching a trace key prefix. Returns up to 1000 matching job objects — there is no pagination beyond that limit.
The traceKeyPrefix query parameter is required; the server returns 400 when it is missing.
Known behavior: the status filter is accepted but silently ignored — the response always includes jobs of all statuses regardless of the filter value.
Narrow the window with createdAt_gte / createdAt_lte when there are many runs for the flow. Because status is silently ignored, filter client-side if you need only completed or errored jobs.
Flow id.
Trace key prefix to search for. The server matches job records whose traceKey begins with this value.
Job status filter. Note: this parameter is currently accepted but silently ignored — all statuses are always returned.
Only return jobs created at or after this ISO 8601 datetime.
Only return jobs created at or before this ISO 8601 datetime.
Maximum number of jobs to return. Capped at 1000.
Matching job objects (max 1000).
Response for a flow-job search by trace key. Returns up to 1000 matching job objects. There is no pagination — the result set is capped at 1000.
Missing required traceKeyPrefix query parameter.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/flows/{_id}/jobs/search?traceKeyPrefix=text HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"runs": [
{
"_id": "69e981ee18808f3e5ed1b2fd",
"_flowId": "69a9aa5c54e3d9bd11b86d82",
"type": "flow",
"status": "completed",
"startedAt": "2026-04-23T02:51:40.000Z",
"endedAt": "2026-04-23T02:52:10.000Z",
"numSuccess": 42,
"numError": 0,
"numIgnore": 1
}
]
}Returns one page of execution-log entries for a specific flow run — one entry per record-at-step (export or import). Entries carry the (_expOrImpId, groupId, recordId, traceKey) tuple needed to drill into per-stage metadata and data via the logs/metadata/query and logs/data/query endpoints.
Execution logs are populated only when the flow has logging enabled (either full logMode or the time-bounded logging.debugUntil debug window). Jobs older than the flow's log retention window will return an empty logs array.
For detailed per-stage data (HTTP request/response, script options.logs output), pick an entry and call POST .../logs/data/query with the corresponding stage. To stitch an export entry to its downstream imports, use the traceKey with POST .../logs/metadata/query.
Flow id.
Flow-run job id (the _id of a type: "flow" job).
Filter log entries by record outcome.
Comma-separated list of export or import step ids. Only entries produced by these steps are returned.
Filter entries whose traceKey starts with this prefix.
Sort direction for log entries by startedAt. Defaults to descending (newest first).
descPossible values: Number of log entries per page. Must be between 1 and 1000.
One page of execution-log entries.
One page of execution-log entries for a flow run. Pagination is body-driven: follow nextPageUrl
to fetch the next page (null when the page is the last). prevPageUrl is populated for navigation
backward from a mid-history page.
URL (absolute or path-relative) for the next page, or null on the last page.
URL for the previous page, or null when already at the head.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/flows/{_id}/jobs/{_jobId}/logs HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"logs": [
{
"startedAt": "2026-04-23T02:51:51.111Z",
"recordId": "f0xVak",
"groupId": "4tQqtS",
"traceKey": "0",
"_expOrImpId": "69a9aa5c54e3d9bd11b86d82",
"status": "success",
"timeTaken": 1232
},
{
"startedAt": "2026-04-23T02:51:45.066Z",
"recordId": "CMeN0hDc",
"groupId": "1WsTiyxQ",
"traceKey": "0",
"_expOrImpId": "69a9aa5d3b213b3ac975e8d2",
"status": "success",
"timeTaken": 1744
}
],
"nextPageUrl": null,
"prevPageUrl": null
}Query execution-log metadata for a record-at-step
Returns per-step timing and outcome metadata for a single record as it traveled through a flow run. When the request includes traceKey, the response spans every step that shared that trace — typically the source export plus its downstream imports.
Pull the _expOrImpId, groupId, recordId, and (optionally) traceKey values from a GET /v1/flows/{_id}/jobs/{_jobId}/logs entry.
Pair this with logs/data/query to build a full per-record trace: this endpoint shows which steps were touched and timing; the data endpoint returns actual payloads. When duplicateTraceKey is true, the traceKey was seen on more than one record in the job, so results may mix records from retries or fan-out. Without traceKey in the request, traceView is false and only the single queried step is returned.
Flow id.
Flow-run job id.
Request body for POST /v1/flows/{_id}/jobs/{_jobId}/logs/metadata/query.
Identifies a single record-at-step within the job's execution log. Include traceKey to widen
the result to every step that shared that trace (export paired with its downstream imports).
Id of the export or import step the record was processed by.
60a2c4e6f321d800129a1a3cThe groupId from the matching execution-log entry.
g_5f8d43a1b9e5a80011a35f2dThe recordId from the matching execution-log entry.
r_0001Optional. When provided, the response includes a traceView across every step that shared this trace key
(e.g. the original export plus its downstream imports).
ORD-100245Step metadata (or a trace across paired steps when traceKey was supplied).
Metadata for a single record-at-step (or for every step sharing a traceKey when the request supplied one).
Returned by POST /v1/flows/{_id}/jobs/{_jobId}/logs/metadata/query.
Echoed back when the request supplied a traceKey; omitted otherwise.
true when the same traceKey was seen on more than one record in this job — useful for spotting
records that got retried or fanned out and may need disambiguation when rendering the trace view.
true when the response contains a multi-step trace (i.e. the request supplied traceKey and paired
steps were found). false when the response is scoped to the single queried step.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
POST /v1/flows/{_id}/jobs/{_jobId}/logs/metadata/query HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 85
{
"_expOrImpId": "69a9aa5d3b213b3ac975e8d2",
"groupId": "1WsTiyxQ",
"recordId": "CMeN0hDc"
}{
"traceKey": "0",
"duplicateTraceKey": false,
"traceView": true,
"steps": [
{
"_expOrImpId": "69a9aa5d3b213b3ac975e8d2",
"recordId": "CMeN0hDc",
"groupId": "1WsTiyxQ",
"status": "success",
"timeTaken": 1744,
"startedAt": "2026-04-23 02:51:45.066",
"completedAt": "2026-04-23 02:51:46.810"
},
{
"_expOrImpId": "69a9aa5c54e3d9bd11b86d82",
"recordId": "f0xVak",
"groupId": "4tQqtS",
"status": "success",
"timeTaken": 1232,
"startedAt": "2026-04-23 02:51:51.111",
"completedAt": "2026-04-23 02:51:52.343"
}
]
}Returns the decoded log data (typically request/response bodies, transform input/output, or script options.logs entries) for a single (step, stage) tuple within a flow run.
Stages are bubble-kind specific. The most useful values:
Export / Lookup:
apiCall(HTTP request+response for HTTP exports),transformation,outputFilter,responseMapping.Import:
apiCall,mapping,inputFilter,responseTransformation.Router:
routing(branching decision).Any: the
functionname from a configured script hook (e.g.preMap,postMap,postSubmit,postResponseMap,preSavePage) — populated only when the hook explicitly callsoptions.logs.push(...).
This is typically the terminal call in the drill-down sequence: execution-logs then metadata/query then data/query. For HTTP traces, set stage: apiCall. A 200 with logs: [] means the stage ran but produced no log entry — usually because a script did not call options.logs.push(), or the stage is not instrumented for that adaptor.
Flow id.
Flow-run job id.
Request body for POST /v1/flows/{_id}/jobs/{_jobId}/logs/data/query.
Fetches the actual data captured at a specific execution stage for a single record-at-step.
Id of the export or import step the record was processed by.
60a2c4e6f321d800129a1a3cExecution stage whose data to return.
Batch id from the execution-log entry.
g_5f8d43a1b9e5a80011a35f2dRecord id from the execution-log entry.
r_0001Log entries for the requested (step, stage).
Stage data for a single record-at-step. Returned by
POST /v1/flows/{_id}/jobs/{_jobId}/logs/data/query.
The payload inside logs[].log is stage-specific. For apiCall, it contains decoded request + response
bodies, headers, status, and duration. For script-hook stages (preMap, postMap, …), it contains
whatever the hook pushed via options.logs.push(...), and is empty (logs: []) when the hook did not log.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
POST /v1/flows/{_id}/jobs/{_jobId}/logs/data/query HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 112
{
"_expOrImpId": "69a9aa5d3b213b3ac975e8d2",
"groupId": "69e981ee18808f3e5ed1b2fd",
"recordId": "0",
"stage": "apiCall"
}{
"logs": [
{
"log": {
"apiCallTraceKeyId": "puP9Xbdn",
"stage": "apiCall",
"apiCallType": "import",
"status": "success",
"request": {
"method": "POST",
"uri": "https://api.example.com/v1/orders"
},
"response": {
"statusCode": 200
}
}
}
],
"errors": []
}List child log records for a parent record
Returns one page of child log records for a specific parent record within a flow-run step. Child records represent sub-operations (e.g. individual batch items, lookup expansions, or retry attempts) spawned by the parent record during step processing.
Use the status query parameter to isolate failures within a batch.
Flow id.
Flow-run job id.
Export or import step id within the flow.
Parent record id whose children to retrieve.
Filter child records by outcome.
Number of child records per page. Must be between 1 and 1000.
One page of child log records.
Paginated response for child log records of a parent record. Follow nextPageUrl to fetch
subsequent pages; prevPageUrl navigates backward. Both are null when at the boundary.
Full URL for the next page, or null on the last page.
Full URL for the previous page, or null when already at the head.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/flows/{_id}/jobs/{_jobId}/{_stepId}/logs/{recordId}/children HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"children": [
{
"startedAt": "2026-04-23T02:51:52.100Z",
"recordId": "ch01xz",
"groupId": "4tQqtS",
"traceKey": "0",
"_expOrImpId": "69a9aa5c54e3d9bd11b86d82",
"status": "success",
"timeTaken": 340
},
{
"startedAt": "2026-04-23T02:51:52.450Z",
"recordId": "ch02ab",
"groupId": "4tQqtS",
"traceKey": "0",
"_expOrImpId": "69a9aa5c54e3d9bd11b86d82",
"status": "error",
"timeTaken": 510
}
],
"nextPageUrl": null,
"prevPageUrl": null
}Executes the flow in test mode and returns the test-run metadata synchronously. Unlike POST /v1/flows/{_id}/run (which queues an asynchronous production job), a test run executes inline against the flow's current configuration and records the per-step stages it produced.
Test runs are kept in a separate history from production runs — the flowJob and childJobs returned here are test artifacts, not records you'll find via GET /v1/jobs. The top-level metadata map is keyed by step id; each value is the ordered list of stage names that step produced (e.g. request, parse, router, input). Use those step ids with GET /v1/flows/{_id}/test/run/{runId}/{_stepId} to inspect per-stage input/output and errors, or with GET /v1/flows/{_id}/test/run/{runId}/{_stepId}/logs/requestAndResponse for raw outbound HTTP captures.
Endpoint template applies across three resource families. The same test-run shape also exists for Tools (/v1/tools/{_id}/test/run) and builder-mode APIs (/v1/apis/{_id}/test/run).
Test-run state is short-lived and ephemeral — capture the runId (the flowJob._id) and read back any step detail soon after the run returns.
Flow id.
Test run executed. Returns the per-step stage metadata, the test
flowJob, and any childJobs produced by the run.
Test-run result envelope.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
POST /v1/flows/{_id}/test/run HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"metadata": {
"69d462d5b9c28ea0b7f82522": [
"request",
"parse"
],
"6a2e23bbcf5b64ca6b93b73d": [],
"69d462d5b9c28ea0b7f82522_input": [
"input"
],
"main": [
"router"
]
},
"flowJob": {
"_id": "6a2e23bbcf5b64ca6b93b757",
"type": "flow",
"_userId": "624cb0346309dc3a543733a2",
"_integrationId": "68ed772471086fb1a76686de",
"_flowId": "69d462d5b9c28ea0b7f82522",
"status": "completed",
"numError": 1,
"numSuccess": 1,
"numPagesGenerated": 1,
"startedAt": "2026-06-14T03:44:59.577Z",
"endedAt": "2026-06-14T03:44:59.947Z",
"createdAt": "2026-06-14T03:44:59.530Z"
},
"childJobs": [
{
"_id": "6a2e23bbcf5b64ca6b93b774",
"type": "export",
"_parentJobId": "6a2e23bbcf5b64ca6b93b757",
"status": "completed",
"numSuccess": 1,
"numPagesGenerated": 1,
"_expOrImpId": "69d462d5b9c28ea0b7f82522"
}
]
}Returns the per-stage input, output, and errors captured for a single step of a flow test run. Each step runs through one or more named stages (e.g. request, parse, input, router); this endpoint returns the ordered stages[] for the requested step plus a top-level errors array aggregating any step-level errors.
The runId is the flowJob._id from the POST /v1/flows/{_id}/test/run response — test runs keep a separate history from production Job records. {_stepId} is one of the step ids from that response's metadata map; the stage names returned here match the stage list that map recorded for the step.
For each stage, input and output are arrays of record envelopes ({record, errors, traceKey}) and may be null when the stage produced no records on that side. Use GET /v1/flows/{_id}/test/run/{runId}/{_stepId}/logs/requestAndResponse when you need the raw outbound HTTP request/response captures instead of the staged record view.
Endpoint template applies across three resource families. The same path shape also exists for Tools (/v1/tools/{_id}/test/run/{runId}/{_stepId}) and builder-mode APIs (/v1/apis/{_id}/test/run/{runId}/{_stepId}).
Test-run state is short-lived and ephemeral — read step detail soon after the run completes.
Flow id.
Test run id (flowJob._id) from the
POST /v1/flows/{_id}/test/run response. Distinct from flow-run Job ids.
Step id whose staged detail you want. One of the keys in the
test-run metadata map.
Per-stage detail for the step. stages[] is the ordered list of
stages the step ran; errors aggregates step-level errors.
Staged detail for a single test-run step.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/flows/{_id}/test/run/{runId}/{_stepId} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"stages": [
{
"name": "request",
"errors": null,
"output": null,
"input": [
{
"record": {
"page": {
"_userId": "624cb0346309dc3a543733a2",
"data": [
{}
]
}
},
"errors": [],
"traceKey": null
}
]
},
{
"name": "parse",
"errors": null,
"input": null,
"output": [
{
"record": {},
"errors": [],
"traceKey": null
}
]
}
],
"errors": []
}Get request/response logs for a flow test-run step
Returns the outbound HTTP request/response log pairs captured during a specific step of a flow test run. Only steps that issued outbound HTTP calls (exports, imports, lookups) produce entries — routers, filters, and other in-process stages are rejected with req_res_logs_not_found by design.
The runId comes from the POST /v1/flows/{_id}/test/run response (not from a normal flow run Job record — test runs and regular runs are separate histories). {_stepId} is the export or import id of the step you want logs for; find the id among the keys in the test-run metadata map.
Endpoint template applies across resource families. The same path shape also exists for Tools (/v1/tools/{_id}/test/run/.../logs/requestAndResponse) and builder-mode APIs (/v1/apis/{_id}/test/run/.../logs/requestAndResponse), but response shapes differ by family: the builder-mode API variant returns a { requests: [] } summary envelope whose entries are resolved via GET /v1/apis/{_id}/{_stepId}/requests/{key}, rather than the array of { request, response } pairs documented here. Refer to each family's spec for its exact response shape.
Response entries may carry base64-encoded JSON in request.body and response.body fields — decode string bodies before parsing. A 404 response is expected for non-HTTP steps (routers, filters); cross-check against the test-run metadata's stage list before treating it as a failure. Test runs are short-lived ephemeral state, so capture logs soon after the run completes.
Flow id.
Test run id from the POST /v1/flows/{_id}/test/run response.
Distinct from flow-run Job ids.
Export or import id of the step whose logs you want. Non-HTTP
stages (routers, filters) 404 with req_res_logs_not_found.
Array of request/response log pairs captured during the step.
request.body / response.body may be base64-encoded JSON.
One request/response pair captured by the test engine.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Either the run/step id didn't resolve, or the step produced no request/response logs (non-HTTP stage — router, filter, etc.).
GET /v1/flows/{_id}/test/run/{runId}/{_stepId}/logs/requestAndResponse HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"request": {
"method": "POST",
"url": "https://httpbin.org/post",
"headers": {
"content-type": "application/json"
},
"body": "eyJuYW1lIjoiQWNtZSBDb3Jwb3JhdGlvbiIsImRvbWFpbiI6ImFjbWUuY29tIn0="
},
"response": {
"statusCode": 200,
"headers": {
"content-type": "application/json"
},
"body": "eyJqc29uIjp7Im5hbWUiOiJBY21lIENvcnBvcmF0aW9uIiwiZG9tYWluIjoiYWNtZS5jb20ifSwidXJsIjoiaHR0cHM6Ly9odHRwYmluLm9yZy9wb3N0In0="
}
}
]Cancels all remaining jobs in a flow execution group. Execution groups are created when multiple flows are triggered together (e.g. via integration-level run or chained flows) and share a common group identifier.
The response varies depending on whether there were jobs left to cancel:
200 with
{"message": "No more jobs to cancel"}when no in-progress jobs remain.204 with no body when cancellation was successfully requested.
This endpoint is not scoped to a specific flow — the _id parameter is the execution group id, not a flow id. Any string is accepted as the id (the server does not validate that the group exists before responding).
Unknown or already-completed group ids return 404 resource_not_found — only groups with cancellable (queued/running) jobs are accepted.
Flow execution group id.
No more jobs to cancel in the group.
Status message.
Cancellation requested for remaining jobs in the group. No response body.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
Not found. The requested resource does not exist or is not visible to the caller.
PUT /v1/flowExecutionGroups/{_id}/cancel HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"message": "No more jobs to cancel"
}Returns the static enumeration values used to filter errors across the platform. The response is not scoped to the authenticated user — every caller receives the same set of filter dimensions and allowed values.
Currently returns two filter dimensions:
source (24 values):
internal,application,connection,resource,transformation,output_filter,input_filter,import_filter,lookup,mapping,response_mapping,pre_save_page_hook,pre_parse_hook,pre_map_hook,post_map_hook,post_submit_hook,post_response_map_hook,post_aggregate_hook,pre_send_hook_ss,pre_map_hook_ss,post_map_hook_ss,post_submit_hook_ss,tool_input,tool_output.classification (10 values):
connection,duplicate,governance,intermittent,missing,parse,value,rate_limit,too_large,none.
The values are static and identical for all callers — cache them aggressively.
Static filter metadata.
Static enumeration metadata for error filters. Returned by GET /v1/errors/filterMetadata.
Values are not scoped to the authenticated user — the same set is returned for every caller.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
GET /v1/errors/filterMetadata HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"filters": [
{
"name": "source",
"enums": [
"internal",
"application",
"connection",
"resource",
"transformation",
"output_filter",
"input_filter",
"import_filter",
"lookup",
"mapping",
"response_mapping",
"pre_save_page_hook",
"pre_parse_hook",
"pre_map_hook",
"post_map_hook",
"post_submit_hook",
"post_response_map_hook",
"post_aggregate_hook",
"pre_send_hook_ss",
"pre_map_hook_ss",
"post_map_hook_ss",
"post_submit_hook_ss",
"tool_input",
"tool_output"
]
},
{
"name": "classification",
"enums": [
"connection",
"duplicate",
"governance",
"intermittent",
"missing",
"parse",
"value",
"rate_limit",
"too_large",
"none"
]
}
]
}Runs a flow's page generators and page processors through the preview pipeline and returns the record arriving at a specific page-processor node, with the whole upstream chain applied server-side: the source export executes live (its transform, output filter, and preSavePage hook are applied), router branch filters and step input filters gate the records, upstream lookups execute live unless a saved mockOutput is present (a saved mock always wins), and upstream imports are NEVER executed — each substitutes its saved mockResponse, or a platform placeholder when none is saved, before its response mapping and postResponseMap hook run. A target IMPORT obeys its map entry's options flag: {preview: true} composes the request and returns it without sending, while {sendAndPreview: true} (the import editor's "Send" button) executes it against the live destination — a real write. A target LOOKUP executes its live query (even when it carries a saved mockOutput — the mock substitutes only when the lookup is upstream of the target). With includeStages: false the response is the bare result object rather than the {data, stages} envelope.
Body carries the flow shape plus resolved maps of page-generator and page-processor docs keyed by _id. The server uses those maps as the source of truth for the preview — it does not read the persisted flow doc, so callers can pass modified versions to "what-if" iterate.
The body field is flow (the API's error message referencing flowDoc is stale). Every entry referenced by flow.pageGenerators[]._exportId must exist in pageGeneratorMap keyed by that id, wrapped as {doc, options}; same for pageProcessorMap. Set includeStages: true to get the stage-by-stage diagnostic array. No job is created and no flow state changes; live calls are limited to the source export, un-mocked upstream lookups, the target lookup, and — only under sendAndPreview — the target import. Upstream imports never call out.
Flow-page-processor preview request. Carries the flow shape plus side-loaded maps of page-generator and page-processor docs so the preview engine can run without reading the persisted flow doc.
The pageProcessor resource id to preview. Must be present as a key
in pageProcessorMap.
64a1234567890abcdef12345Page generator to drive the preview when the flow has multiple.
Defaults to flow.pageGenerators[0]._exportId.
61f92026dd053843b5d72350Include stage-by-stage diagnostics (stages[]) in the response.
Recommended — without it the response loses the per-stage data and
error breakdown. When false, the preview instead behaves as an
input-data preview: the flow is stripped before the target step and
the response carries the records the target would receive as input
(for a lookup step, with its responseMapping already merged in).
Preview envelope. Mirrors ExportPreviewResponse — stages[] carries
the stage-by-stage output + errors, and the top-level errors[]
aggregates any configuration failures surfaced during the run.
Envelope returned by POST /v1/exports/preview (and the scoped
/v1/integrations/{_integrationId}/flows/{_flowId}/exports/preview
variant). Carries per-stage diagnostics alongside the sampled records.
URIs for any files produced by the preview (e.g. file-based exports writing to cloud storage). Empty for non-file adaptors.
Trace keys for the records in this preview — one per record, correlating stage outputs to their source record.
Trace keys that collided during the preview — a diagnostic for trace-key generation; rarely non-empty in practice.
Request structural errors.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
POST /v1/pageProcessors/preview HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 654
{
"flowDoc": {
"name": "Accounts: HubSpot to NetSuite",
"pageGenerators": [
{
"_exportId": "652583cf9085040ecbf54303"
}
],
"pageProcessors": [
{
"type": "import",
"_importId": "6508ab8b20b16404da729c64"
}
]
},
"_pageProcessorId": "6508ab8b20b16404da729c64",
"_selectedPageGeneratorId": "652583cf9085040ecbf54303",
"pageGeneratorMap": {
"652583cf9085040ecbf54303": {
"doc": {
"_id": "652583cf9085040ecbf54303",
"name": "Get HubSpot Accounts",
"adaptorType": "HTTPExport"
},
"options": {}
}
},
"pageProcessorMap": {
"6508ab8b20b16404da729c64": {
"doc": {
"_id": "6508ab8b20b16404da729c64",
"name": "Upsert NetSuite Customers",
"adaptorType": "NetSuiteImport"
},
"options": {
"preview": true
}
}
},
"includeStages": true
}{
"data": [
{
"id": "851",
"name": "Acme Corporation",
"domain": "acme.com"
}
],
"dataURIs": [],
"dataRecordTraceKeys": [
"851"
],
"stages": [
{
"name": "apiCall",
"data": [
{
"id": "851",
"name": "Acme Corporation",
"domain": "acme.com"
}
],
"errors": null
}
]
}Returns the set of resources that depend on the specified resource. The response is an object whose keys are dependent-resource types (e.g. flows, imports) and whose values are arrays of dependency entries.
An empty object {} means no other resources depend on the target — this is also returned for a well-formatted but nonexistent id.
Resource ID.
Dependency map. Keys are resource-type strings; values are arrays
of dependency entries. Returns {} when no dependents exist.
Map of dependent-resource types to arrays of dependency entries.
Keys are plural resource type strings (e.g. flows, imports,
connections). An empty object {} means no dependents.
Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.
Note: the 401 response is produced by the auth middleware before the
request reaches the endpoint handler, so it does not follow the
standard {errors: [...]} envelope. Instead the body is a bare
{message: string} object with no code, no errors array. Callers
handling 401s should key off the HTTP status and the message string,
not try to destructure an errors[].
GET /v1/flows/{_id}/dependencies HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}Last updated
Was this helpful?