This reference covers the three run modes available for connector runs, details on Comprehensive Mode behavior, and how to use dry runs to preview changes before applying them.

Run Modes

There are three run modes to choose from when running a connector: Default, Comprehensive, and Deletion.

Default Mode

• New entities present in the run will be created.
• Existing entities will be updated (or remain unchanged).
• No entities will be deleted.

Use Default Mode for connectors that ingest new data and update existing data, without the assumption that missing data should be deleted.

Comprehensive Mode

The connector treats each run as a comprehensive data set:

• New entities present in the run will be created.
• Existing entities will be updated (or remain unchanged).
• Any entities created by a previous run of the same connector that are not present in the current run will be deleted.

An entity ID must be specified for all entities in a Comprehensive Mode run. If any entity IDs are missing, the run will display an error: "Entity ID is missing or blank."

If any ETL error occurs at any point during a Comprehensive Mode run — including during the Transform stage — the entire run will fail. No entities will be created, updated, or deleted.

Use case: Comprehensive Mode works well for connectors that fetch the entire data set each time they run. Anything missing from that data set is assumed to have been deleted from the source system and will be deleted in Yext.

For full details on Comprehensive Mode behavior and configuration, see Comprehensive Mode Configuration below.

Deletion Mode

The connector deletes every entity present in the run:

• No entities will be created, updated, or left unchanged.
• Any entity in Yext whose entity ID appears in the data set will be deleted.

Use case: Deletion Mode works well for Push to API connectors that need to delete specific entities when they are removed from the source system, and each push is not a comprehensive data set. It is unlikely to be used for Pull connectors unless the goal is to delete all entities created by the connector (e.g., to reset after a misconfiguration).

Setting the Run Mode

Scheduled Runs

Scheduled runs have a run mode tied to their schedule. Schedules are supported on these sources: Pull from API, Crawler, Functions, and any Native Source.

Each scheduled run executes in the specified mode, either Default or Comprehensive. Deletion Mode is not supported for scheduled runs.

Run schedules can be configured on the Connectors Summary page by clicking View.

Run Now

When triggering a run on-demand via the Run Now button, you can specify the mode: Default, Comprehensive, or Deletion. The primary Run Now action always triggers Default Mode.

API

Push Connectors: POST /pushData

Use the runMode query parameter to specify the run mode:

• DEFAULT
• COMPREHENSIVE
• DELETION

If omitted, runMode defaults to DEFAULT. To run in Deletion or Comprehensive Mode, the query parameter must be set on every request.

POST /trigger

The trigger endpoint can be used for: Pull, Crawler, Function, File Upload, and any Native Source.

Use the runMode query parameter for the {connectorId}/trigger endpoint:

• DEFAULT
• COMPREHENSIVE
• DELETION

If omitted, runMode defaults to DEFAULT.

Comprehensive Mode Configuration

Configure the comprehensive data set and missing entity behavior in Connector Configuration > Advanced Settings, after the Mapping stage.

Comprehensive set: By default, this is any entity ever created by the given connector. Optionally, you can scope it to entities within a specified saved filter.

Missing entities: By default, any entities missing from the run (as defined by the comprehensive set) will be deleted. Optionally, you can instead define a set of updates to apply to those missing entities.

Update Missing Entities

Configuring updates for missing entities follows three stages: Extract, Transform, and Map. The missing entities are treated as the "source" for this flow.

Specify Selectors

Select the fields to be modified in subsequent stages. Not all selected fields need to be mapped — they simply become available for use in the Transform stage.

Adding default selectors will extract the same fields mapped in the primary connector flow. To manually add selectors, specify a column header and select the field to extract from.

Available fields include almost any enabled field on the connector's entity type. The following are not available:

• Entity Relationship type fields
• Folders
• Categories
• Linked Accounts
• ECLs
• Rich Text v1 (Legacy Rich Text) fields

Note: Rich Text (v2) fields are supported. To use Rich Text (v1) fields, migrate them first: Migrate Legacy Rich Text Fields and Field Types

The preview table shown when configuring selectors is populated with the 10 most recently updated entities of the configured entity type. This is example data — the actual missing entities can only be determined at run time.

Add Transforms

Transform extracted data using any built-in or custom function transforms.

It is not recommended to modify the Entity ID column during this stage. If the Entity ID column is manipulated, the "missing set" will reflect the current (modified) Entity IDs, which could result in unintentional updates to other entities or unintentional entity creation.

Map Data

Map columns to fields on the configured entity type. Unmapped columns are ignored. This follows the same behavior as the standard Mapping stage — see the Map Fields reference for more information.

Analyzing Run Results

When running in Comprehensive Mode, a downloadable file of all missing entity IDs is available in the run results.

Note that this file reflects the missing entity IDs before any data manipulation steps. As mentioned above, modifying the Entity ID column can affect this set.

Missing entities are included in the Created / Updated / Unchanged / Failed / Deleted entity counts. This means those totals may exceed the number of entities in the current run, since they include results from the comprehensive set.

Example: Connector A pulls location data from a file, with the comprehensive set defined as all entities in the "Open Locations" saved filter. Comprehensive Mode is configured to append -CLOSED to the Name field of any missing entities.

• The current file has 25 entities to update; 5 are missing from the comprehensive set.
• The updated entity count will be 30 — 25 from the current run, plus 5 missing entities that were updated.

Run Breakers in Comprehensive Mode

Run breakers operate on the count of entities in the source data and the initial count of missing entities for that run. They do not factor in what actually happens to the missing entities (e.g., whether they are updated), to avoid duplicate actions on the same entity.

A common use case is breaking a run if too many entities are missing from the comprehensive set. Configure the run breaker on the comprehensive set with a threshold for missing entities if the count exceeds that threshold, the run is aborted.

See the Run Breakers documentation for configuration details.

Entity Type Mismatch

If the entity type is changed, or if the comprehensive set is defined by a saved filter containing multiple entity types, the entity type of some "missing" entities may not match the type configured in the source data. Any missing entities whose entity type doesn't match will fail to update.

Dry Runs

Dry runs let you run a connector and preview the results without applying any changes to the account.

When a dry run is initiated, Yext processes all selectors, transforms, and mappings — but does not send updates to the Knowledge Graph. Instead, it displays what changes would occur if the run were executed. Updates are only applied once the dry run results are approved.

Triggering a Dry Run

Any connector run can be initiated as a dry run via:

1. The manual run trigger in the UI
2. Scheduled runs
3. The /trigger endpoint with the query parameter dryRun=true
4. The /push endpoint with the query parameter dryRun=true

Reviewing a Dry Run

Once complete, a dry run will be in "Ready for Review" status. Result counts can be viewed in the Connectors UI or via the API. Dry run results are marked with a "Dry Run" pill in the UI to distinguish them from live runs. Detailed results are available for download in the Results file.

A completed dry run can be approved or abandoned:

• Approved: The previously processed data is applied to the Knowledge Graph. The data is not re-processed — this means any changes to the connector configuration or source data made between initiating and approving the dry run will not be reflected. Similarly, if an entity included in the dry run was modified or deleted before approval, the final result may differ from what the dry run displayed.
• Abandoned: The dry run results are discarded and no changes are applied.

Approve or abandon via the Connectors UI or the /approve and /cancel API endpoints.

Users have 7 days after initiation to approve or abandon. After 7 days, the dry run is automatically abandoned. Dry runs not in a Completed or Completed with Errors status cannot be approved.

Limitations

Categories, Google Attributes, and Folders may appear valid in a dry run but fail during an actual run, due to additional validation that occurs in downstream services. For example, the system will not validate whether a given category is eligible for an entity based on the account's Yext subscription.

Additionally, the system cannot detect whether values in these field types are updated or unchanged compared to current values. If all other fields on an entity are unchanged, the entity will be registered as "Unchanged" in the dry run, but a warning will indicate that a comparison was not performed, and an update to Categories, Google Attributes, or Folders could still occur on an actual run.