> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://docs.mammoth.io/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://docs.mammoth.io/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"}]}
```

**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://docs.mammoth.io/learn/automations/) 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—no API call, polling, or scheduled run time needed. This is already available; see [Incremental processing → Pattern 3](https://docs.mammoth.io/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://docs.mammoth.io/learn/automations/triggers#webhook-data-ingestion) 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 it until its `status` resolves (`success`, `failure`, `processing`, or `error`), then read the result rows. For an actual downloadable CSV/Excel file rather than JSON rows, add an export step to the pipeline itself—that's configured in the pipeline, not requested ad hoc 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.

### Direct API write via external system

For writing results back to an API, the pattern requires an intermediary:

1. Mammoth prepares the transformed data
2. **Export** → **Databases** to BigQuery, PostgreSQL, SQL Server, or Redshift (kept current by Auto-sync on each pipeline run)
3. A lightweight external script (Cloud Function, Lambda, [Make.com](https://www.make.com) webhook) reads from that database and writes to the target API

Mammoth does not write to arbitrary APIs. Use it for transformation and delegate API writes to a purpose-built integration tool.

---

## Mammoth's external API

Mammoth's REST API allows external systems to trigger and monitor automations programmatically. The active API is versioned at `/api/v2`.

### 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"}]}
```

**Get an automation's last run status:**

```http
GET /api/v2/workspaces/{workspace_id}/projects/{project_id}/automations/{automation_id}
Authorization: Bearer {api_token}
# Returns last_run and last_run_result: Mammoth surfaces the most recent run, not a full run history
```

**Fetch a View's data:**

```http
GET /api/v2/workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/dataviews/{dataview_id}/data
Authorization: Bearer {api_token}
# Async job: poll until status is "success", then read the result
```

**Check View status:**

```http
GET /api/v2/workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/dataviews/{dataview_id}
Authorization: Bearer {api_token}
# Returns row_count, status, pipeline_status: there's no last-refreshed timestamp field
```

### API authentication

API credentials are **API tokens**, created in **Workspace settings → API Tokens**. 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. The older `X-API-KEY` and `X-API-SECRET` headers are deprecated. See [Authentication](https://docs.mammoth.io/build/auth).

**Security:**

- A token is shown only once—store it securely 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, use polling rather than synchronous waiting:

```python
import requests
import time

headers = {
    "Authorization": f"Bearer {api_token}",
}

# Trigger the automation
requests.patch(
    f"https://app.mammoth.io/api/v2/workspaces/{workspace_id}/projects/{project_id}/automations/{automation_id}",
    headers=headers,
    json={"patch": [{"op": "command", "path": "run"}]},
)

# Poll the View for the refreshed status
while True:
    view = requests.get(
        f"https://app.mammoth.io/api/v2/workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/dataviews/{dataview_id}",
        headers=headers,
    ).json()

    if view["pipeline_status"] == "ready":
        break
    elif view["pipeline_status"] == "error":
        raise Exception(f"Pipeline failed for dataview {dataview_id}")

    time.sleep(30)  # Check every 30 seconds

print("Pipeline completed. Fetching results...")
```

## 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 for completion—if status is `error`, inspect the failure
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://docs.mammoth.io/guides/advanced/api-workflows.md · Updated: 2026-10-13