> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://mammoth.io/docs/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# API workflows

> Trigger Mammoth automations through the REST API, poll for completion, fetch View data, and push results to external systems, with Python examples.

Mammoth's REST API lets external systems trigger automations and monitor their status programmatically. This guide covers the trigger options, how to fetch results, and integration patterns such as fan-out, fan-in, and retry. A file-arrival trigger already exists for Data Consolidation automations (see Pattern 3 in [Incremental processing](https://mammoth.io/docs/guides/advanced/incremental/)). To push data into Mammoth from an external system, see [Webhook data push](#webhook-data-push).

## Trigger patterns

### API trigger (production)

Trigger an automation from any external system using Mammoth's REST API. Use this when you need to kick off a pipeline run from CI/CD, a scheduler, or another backend service.

```http
PATCH /api/v2/workspaces/<workspace_id>/projects/<project_id>/automations/<automation_id>
Authorization: Bearer <api_token>
Content-Type: application/json

{"patch": [{"op": "command", "path": "run", "value": ""}]}
```

**Supported scenarios:**

- CI/CD pipeline completes a deployment → trigger a data refresh for release metrics
- Scheduled job in an external system → trigger a Mammoth automation at a precise time
- Business system completes processing → kick off downstream data pipeline

### Schedule trigger (production)

Configure automations to run on a time-based schedule (daily, weekly, monthly) without any external system integration. See [Automations](https://mammoth.io/docs/learn/automate/) for the full setup guide.

### File-arrival trigger (production)

A Data Consolidation automation watches a source Data Library folder and picks up files as they are added. It needs no API call, polling or scheduled run time. This is already available; see [Incremental processing → Pattern 3](https://mammoth.io/docs/guides/advanced/incremental/) for the full setup.

### Webhook data push

To send data into Mammoth from systems such as Shopify, Stripe, or Salesforce, create a webhook dataset. The external system POSTs its payload to the dataset's webhook URL and Mammoth ingests it. See [Triggers](https://mammoth.io/docs/learn/automate/schedules-and-triggers/#receive-data-pushed-by-webhook) for setup. To start a pipeline run from an external event, call the API trigger above.

## Push patterns: Sending results to external systems

### Export via API after pipeline completion

After a pipeline runs (triggered by API or schedule), fetch its results via the dataview's data endpoint:

```http
GET /api/v2/workspaces/<workspace_id>/projects/<project_id>/datasets/<dataset_id>/dataviews/<dataview_id>/data
Authorization: Bearer <api_token>
```

This returns an async **Job**. Poll `GET /api/v2/jobs/<job_id>` while its `status` is `processing`; when it is `success`, read the rows from the job's `response`. A `failure` or `error` status ends it too. For an actual downloadable CSV/Excel file rather than JSON rows, add an export step to the pipeline itself. That is set up in the pipeline, not requested through this endpoint.

**Use cases:**

- Pull clean data into a downstream system after Mammoth processing
- Feed Mammoth output into a BI tool or warehouse via a scheduled script
- Integrate Mammoth into a broader data orchestration workflow (Airflow, Prefect, etc.)

### Notifying another system on completion

Messaging delivers by email. To notify another system when a run finishes, poll the automation or Job status as shown in this guide, then POST to your own endpoint from your system.

### Send results to an API or a database

To write results to another system, add an export step to the View:

- **REST API Export** sends the View's rows to an HTTP endpoint you configure. It is available on plans that include Tableau Server and REST API exports.
- Database destinations: PostgreSQL, MySQL, SQL Server, Amazon Redshift, Google BigQuery and Elasticsearch (on plans that include database exports), and Snowflake, Databricks and Google Sheets (open to every plan).

An export step runs after each data update. To run it on a clock instead, put it in a [Scheduled Export](https://mammoth.io/docs/learn/automate/) automation.

If the target API needs logic an export can't express, export to a database and let a small external script (Cloud Function, Lambda, a [Make.com](https://www.make.com) scenario) read it and call the API.

---

## Mammoth's external API

Mammoth's REST API lets external systems trigger and monitor automations. Every path starts with `https://app.mammoth.io/api/v2`. The older v1 API is legacy: build new integrations on v2 only.

### Key endpoints

**Trigger an automation:**

```http
PATCH /api/v2/workspaces/<workspace_id>/projects/<project_id>/automations/<automation_id>
Authorization: Bearer <api_token>
Content-Type: application/json

{"patch": [{"op": "command", "path": "run", "value": ""}]}
```

`value` is required, even for `run`: leave it out and the request fails with 400 `VALIDATION_ERROR` (`4GENR007`). A suspended automation refuses to run with 400 and "Automation is suspended; resume it before running". To suspend or restore one, send `{"op": "replace", "path": "status", "value": "suspend"}` or `"value": "restore"`.

**Get an automation's status:**

```http
GET /api/v2/workspaces/<workspace_id>/projects/<project_id>/automations/<automation_id>
Authorization: Bearer <api_token>
# {"automation": {"id": ..., "status": "active", "execution_status": "running", "tasks": [...], ...}}
```

`execution_status` is `running` while any of the automation's tasks is queued or running, and `idle` otherwise. `status` is `active`, `suspended` or `failed`. Each entry in `tasks` carries `last_run` (when it last ran) and `last_run_result`, which holds a `failure_reason` when that run failed.

**Get an automation's run history:**

```http
GET /api/v2/workspaces/<workspace_id>/projects/<project_id>/automations/<automation_id>/runs?limit=50
Authorization: Bearer <api_token>
# {"runs": [{"id": ..., "trigger": ..., "started_at": ..., "finished_at": ..., "files": [...]}]}
```

The latest runs, newest first, each with its files. At most 50 come back.

**Fetch a View's data:**

```http
GET /api/v2/workspaces/<workspace_id>/projects/<project_id>/datasets/<dataset_id>/dataviews/<dataview_id>/data?limit=400&offset=0
Authorization: Bearer <api_token>
# 202: {"job": {"id": 14794754, "status": "processing", ...}}
```

The answer is a job. Read it with `GET /api/v2/jobs/<job_id>` until `status` is `success` (the rows are in `job.response`) or `failure` or `error`. `GET /api/v2/jobs/<job_id>/stream` waits for you instead; see [asynchronous jobs](https://mammoth.io/docs/build/#asynchronous-jobs). `limit` defaults to 400 rows. To filter rows, `POST` to the same path with a JSON body that adds a `condition`.

**Check View status:**

```http
GET /api/v2/workspaces/<workspace_id>/projects/<project_id>/datasets/<dataset_id>/dataviews/<dataview_id>?fields=__full
Authorization: Bearer <api_token>
# Returns row_count, status, data_updated_at, pipeline_status, ...
```

`data_updated_at` is when the view's data last changed. `pipeline_status` (`ready`, `running`, `error` and a few in-between states) comes back only when you ask for it, with `fields=__full` or a list such as `fields=pipeline_status,data_updated_at`. Without `fields` you get the standard set, which leaves it out.

### API authentication

API credentials are **API tokens**, created in **Settings → API Keys**: in the **API tokens** card, choose **Generate key**. A token starts with `mm_` and belongs to one workspace, not to an individual user; it can also be limited to one project, and then gets HTTP 403 in every other project. Requests send it as `Authorization: Bearer <api_token>`; no workspace header is needed, and the workspace id in the URL path must be the token's own workspace. `GET /api/v2/workspaces/current` tells you which workspace that is. The older `X-API-KEY` and `X-API-SECRET` headers are deprecated. See [Authentication](https://mammoth.io/docs/build/auth/).

**Security:**

- A token is shown only once: store it in your secrets manager
- Rotate credentials when team members change or access needs change

### Polling pattern for long-running pipelines

For pipelines that take minutes to complete, poll rather than hold a request open. Trigger the automation, wait until it is idle again, then check its tasks for a failure:

```python
import os
import time

import requests

BASE = "https://app.mammoth.io/api/v2"
headers = {"Authorization": f"Bearer {os.environ['MAMMOTH_API_TOKEN']}"}
workspace_id, project_id, automation_id = 11, 10, 42  # your ids
url = f"{BASE}/workspaces/{workspace_id}/projects/{project_id}/automations/{automation_id}"

# Trigger the automation
r = requests.patch(url, headers=headers, json={"patch": [{"op": "command", "path": "run", "value": ""}]})
r.raise_for_status()

# Poll until no task is queued or running
time.sleep(10)  # give the run a moment to queue its tasks
while True:
    r = requests.get(url, headers=headers)
    if r.status_code == 429:
        time.sleep(int(r.headers.get("Retry-After", "60")))
        continue
    r.raise_for_status()
    automation = r.json()["automation"]
    if automation["execution_status"] == "idle":
        break
    time.sleep(30)

failures = [t["last_run_result"]["failure_reason"] for t in (automation.get("tasks") or [])
            if (t.get("last_run_result") or {}).get("failure_reason")]
if failures:
    raise RuntimeError(f"Automation {automation_id} failed: {failures}")
print("Automation finished. Fetch the results next.")
```

## Integration patterns

### The fan-out pattern

One file drop can already trigger multiple independent automations today. Create a separate Data Consolidation automation on the same source folder for each downstream pipeline that needs to react. Each one runs automatically whenever a file is added to the folder; Data Consolidation has no schedule or trigger setting to configure. For fan-out from other external events, call each automation's API trigger endpoint in turn from your external system.

### The fan-in pattern

Multiple Mammoth automations must all complete before a downstream pipeline runs. Use a coordination layer outside Mammoth:

1. Each upstream Mammoth automation is triggered via API
2. Your coordination script polls each automation's status until complete
3. When all prerequisites finish, it triggers the downstream automation via the API

### The retry pattern

For flaky source systems (APIs that occasionally return errors or empty responses):

1. Trigger the automation via API
2. Poll until `execution_status` is `idle`. If a task's `last_run_result` carries a `failure_reason`, inspect it
3. Retry by triggering it again up to N times with a delay between attempts
4. If all retries fail, alert via your external notification system

---
Source: https://mammoth.io/docs/guides/advanced/api-workflows.md · Updated: 2026-11-02
