canonical: https://jentic.com/apis/app.coalescesoftware.io/coalescesoftware

# Coalescesoftware Jobs

The Coalesce Jobs API lets data teams trigger, monitor, and manage data transformation runs in the Coalesce platform programmatically. Operations cover starting and cancelling scheduled runs, listing environments and nodes, and retrieving run results so transformation pipelines can be orchestrated from external schedulers or CI workflows. The API is available across Coalesce regional deployments on AWS, Azure, and GCP and authenticates with bearer tokens or an Authorization header API key.

## For AI agents

Trigger Coalesce data transformation runs, list environments and nodes, and fetch run results so an agent can orchestrate Snowflake pipelines without using the Coalesce UI.

## Scope

Does not handle data ingestion, warehouse provisioning, or BI dashboarding - use for orchestrating Coalesce transformation runs only.

## Capabilities

- Trigger a scheduled Coalesce run via the `/scheduler/startRun` endpoint
- Cancel an in-flight run with `/scheduler/cancelRun` before it consumes more compute
- Re-run a failed transformation through `/scheduler/rerun` without rebuilding the schedule
- List environments and inspect nodes inside an environment for pipeline introspection
- Pull run status and per-node results to drive downstream alerting
- Page through historical runs to audit which transformations executed in a window

## Use cases

### External Scheduler Integration

Orchestrate Coalesce transformation runs from Airflow, Dagster, or a custom scheduler by calling `/scheduler/startRun` with the target environment and job, then polling `/scheduler/runStatus` until the run completes. This pattern replaces relying on Coalesce's built-in scheduler when teams already have a wider data orchestration stack and want a single source of truth for DAG dependencies.

Example prompt: Call POST `/scheduler/startRun` with environmentID and jobID, then poll `/scheduler/runStatus` every 30 seconds until status is SUCCESS or FAILED and surface the result

### Run Failure Recovery

Detect failed Coalesce runs from a monitoring layer and recover by calling `/scheduler/rerun` with the failed run ID. Combined with `/api/v1/runs/{runID}/results` this lets a recovery agent identify which nodes failed, decide whether a rerun is safe, and trigger it without human intervention for idempotent transformations.

Example prompt: Fetch GET `/api/v1/runs/{runID}/results` for the latest failed run, identify node failures, and call `/scheduler/rerun` if all failed nodes are marked retry-safe

### Environment and Node Discovery

Build internal tooling that documents which Coalesce environments and nodes exist across regions by listing `/api/v1/environments` and walking nodes for each environment. This is useful for governance teams cataloguing transformation assets or building lineage graphs across multiple Coalesce deployments.

Example prompt: List all environments via GET `/api/v1/environments`, then for each environment enumerate nodes via `/api/v1/environments/{environmentID}/nodes` and write a flat catalog to storage

### Agent-Driven Pipeline Operations

Allow an AI agent to manage Coalesce data pipelines through natural language by exposing run start, cancel, rerun, and status checks as Jentic operations. The agent looks up Coalesce by intent, loads the operation schema, and executes calls without storing the bearer token in conversation context.

Example prompt: Search Jentic for 'trigger a coalesce run', load the startRun schema, and execute the call with environment 'prod' and the job ID requested by the user

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/scheduler/startRun` | Trigger a scheduled run |
| GET | `/scheduler/runStatus` | Check status of a run |
| POST | `/scheduler/rerun` | Re-run a failed job |
| POST | `/scheduler/cancelRun` | Cancel an in-flight run |
| GET | `/api/v1/environments` | List environments |
| GET | `/api/v1/runs` | List runs |
| GET | `/api/v1/runs/{runID}/results` | Get results for a specific run |

## Key resources

- **Environments** — List Coalesce environments and fetch nodes inside an environment
- **Runs** — List historical runs, fetch run details, and pull per-node results
- **Scheduler** — Start, cancel, rerun, and check status of scheduled transformation jobs
- **Nodes** — Inspect transformation nodes within a specific environment

## Why Jentic

- **Setup:** Wiring Coalesce by hand means managing its dual bearer token and Authorization API key, and choosing the right regional host among its US, EU, Australia, and private-link servers yourself. Through Jentic you install once, import the Coalesce Jobs API from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Coalesce puts the run id in the URL path (`/api/v1/runs/{runID}/results`) while run control travels through the scheduler operations, so you limit the agent to the operations it needs, such as starting a run and checking run status. You choose the operations it may call, so cancelRun and rerun are not included unless you add them.
- **Credential handling:** Your Coalesce bearer token and Authorization API key are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'trigger a Coalesce run' or 'check run status', and Jentic returns the matching scheduler operation with its input schema so the agent calls the right endpoint without browsing Coalesce docs.

## Related APIs

- **Snowflake API** — Coalesce transformations execute against Snowflake - call Snowflake directly for query results and warehouse control
- **Airbyte API** — Airbyte ingests source data; Coalesce transforms it once landed in the warehouse
- **GitLab API** — GitLab CI/CD pipelines can be used as a generic scheduler instead of Coalesce's built-in scheduler

## FAQ

### What authentication does the Coalesce Jobs API use?

The Coalesce Jobs API supports two schemes: HTTP bearer tokens and an apiKey passed in the Authorization header. Through Jentic the bearer token is held in the encrypted vault (your Jentic One instance) and never enters agent context - agents receive scoped, short-lived access only.

### Can I trigger a Coalesce run programmatically with this API?

Yes. POST `/scheduler/startRun` starts a scheduled run for a given job and environment, and `/scheduler/runStatus` returns its current state. `/scheduler/cancelRun` and `/scheduler/rerun` give you control over in-flight and failed runs respectively.

### What are the rate limits for the Coalesce Jobs API?

The OpenAPI spec does not publish explicit rate limits. Coalesce runs are gated by your warehouse compute and account plan rather than a per-minute API quota - check your Coalesce account dashboard for current limits before high-frequency polling.

### How do I trigger a Coalesce run through Jentic?

Run pip install jentic, then search for 'trigger a coalesce run' through the Jentic SDK. Jentic returns the `/scheduler/startRun` operation with its input schema; load the schema, populate environmentID and jobID, and execute.

### Which Coalesce regions does this API cover?

The spec lists base URLs for US, EU, Canada, and Australia across AWS, Azure, and GCP, including PrivateLink variants for AWS. Pick the server URL that matches your Coalesce deployment region - the path layout is identical across regions.

### Can I get per-node results for a completed run?

Yes. GET `/api/v1/runs/{runID}/results` returns the per-node outcome for a specific run, which is the recommended way to drive failure-recovery logic before calling `/scheduler/rerun.`

### Can I limit what my agent is allowed to do with the Coalesce Jobs API?

Yes. Because Jentic One is self-hosted, your own rules decide which Coalesce operations the agent may call, so you can grant it just POST `/scheduler/startRun` and GET `/scheduler/runStatus` to trigger runs and watch their status. Run-control operations like `/scheduler/cancelRun` and `/scheduler/rerun` stay off limits unless you explicitly add them, and the run id lives in the URL path (`/api/v1/runs/{runID}/results`) rather than being something the agent picks freely. The bearer token and Authorization API key are held by your instance and injected only at execution time, so scoping the operation list controls exactly what the agent can do.