---
title: "Workflow Audit API | Jetstack AI Docs"
description: "Start HubSpot workflow audits, poll them and read findings, dependencies, enrollment paths, assets and evidence over the Jetstack AI REST API."
url: "https://jetstack.ai/docs/developers/workflow-audit-api/"
---

# Workflow Audit API

The Workflow Audit API runs the same workflow audit you can run in the app, from your own scripts, pipelines or agents. You start an audit on a connected HubSpot portal, poll it until it finishes, then page through the results: the workflow inventory, findings, direct dependencies, enrollment paths, referenced assets and health scores. You can also save notes, finding dispositions and workflow decisions back to the audit.

If you are new to workflow audits, start with the [Workflow Audit Overview](https://jetstack.ai/docs/audits/workflow-audits/overview). Every endpoint, parameter and response schema is in the [interactive API reference](https://jetstack.ai/api).

No endpoint in this API enables, disables, edits or deletes a HubSpot workflow. Findings describe how workflows are **configured**. They are not a record of what ran: every investigation response says `"basis": "configuration"` and `"runtimeExecutionAssessed": false`.

## Before You Start

- **An API key with the right scopes.** Create one in the app under **Settings → Access Tokens**. Reading needs `audit:read`. Starting an audit and saving a review need `audit:write`. The read-only preset includes `audit:read`; the operator and full-access presets include both.
- **A connected HubSpot portal.** The portal must be connected to your organization, and its HubSpot connection must grant the `automation` scope. If it doesn’t, starting an audit returns `400` with `WORKFLOW_AUDIT_HUBSPOT_FETCH_FAILED`. Reconnect the portal after granting the scope.
- **The base URL** is `https://api.jetstack.ai`. Send your key as `Authorization: Bearer jsai_…`. If your organization runs on a dedicated Jetstack instance, also send `X-Instance-Id` with the value shown in **Settings → Access Tokens → Connection Details**. Everyone else leaves it out.

See [Authentication](https://jetstack.ai/docs/developers/authentication) for key management, scopes and rate limits.

The examples below assume:

Terminal window

```
export  JETSTACK_API_KEY = "jsai_your_api_key"
```

## Endpoints

All paths are relative to `https://api.jetstack.ai`.

| Method | Path                                                              | Scope         | What it does                                                    |
| ------ | ----------------------------------------------------------------- | ------------- | --------------------------------------------------------------- |
| `POST` | `/v1/workflow-audits`                                             | `audit:write` | Start an audit                                                  |
| `GET`  | `/v1/workflow-audits`                                             | `audit:read`  | List runs, newest first                                         |
| `GET`  | `/v1/workflow-audits/{runId}`                                     | `audit:read`  | Status, progress and headline numbers                           |
| `GET`  | `/v1/workflow-audits/{runId}/summary`                             | `audit:read`  | Totals, portfolio score and coverage                            |
| `GET`  | `/v1/workflow-audits/{runId}/workflows`                           | `audit:read`  | The workflow inventory, paginated and searchable                |
| `GET`  | `/v1/workflow-audits/{runId}/workflows/{workflowId}`              | `audit:read`  | One workflow in full, with a plain-language brief and its score |
| `GET`  | `/v1/workflow-audits/{runId}/workflows/{workflowId}/dependencies` | `audit:read`  | Direct relationships, with evidence                             |
| `GET`  | `/v1/workflow-audits/{runId}/workflows/{workflowId}/paths`        | `audit:read`  | Upstream and downstream enrollment paths                        |
| `GET`  | `/v1/workflow-audits/{runId}/assets`                              | `audit:read`  | Every referenced asset, with reader and writer counts           |
| `GET`  | `/v1/workflow-audits/{runId}/asset?assetKey=…`                    | `audit:read`  | The workflow references for one asset                           |
| `GET`  | `/v1/workflow-audits/{runId}/findings`                            | `audit:read`  | Configuration findings                                          |
| `GET`  | `/v1/workflow-audits/{runId}/reviews`                             | `audit:read`  | Notes, finding dispositions and decisions                       |
| `PUT`  | `/v1/workflow-audits/{runId}/reviews`                             | `audit:write` | Save a note, disposition or decision                            |
| `GET`  | `/v1/workflow-audits/{runId}/evidence?kind=…`                     | `audit:read`  | Bounded pages of stored evidence                                |
| `GET`  | `/v1/workflow-audits/{runId}/result`                              | `audit:read`  | The full result in one response                                 |

Use these paths exactly. A trailing slash, an unknown sub-path or an unsupported method returns `404` with `REST_API_NOT_FOUND`.

## Run an Audit

1. **Start the audit.**

   `portalId` accepts the HubSpot portal ID or the Jetstack portal ID from `GET /v1/portals`. `name` is required, up to 200 characters. `scope.objectTypes` limits the audit to some HubSpot object types (up to 50, such as `0-1` for contacts and `0-2` for companies); leave `scope` out to audit every supported object type.

   Terminal window

   ```
   curl   -X   POST   https://api.jetstack.ai/v1/workflow-audits   \
      -H   "Authorization: Bearer  $JETSTACK_API_KEY "   \
      -H   "Content-Type: application/json"   \
      -H   "Idempotency-Key: $( uuidgen )"   \
      -d   '{
        "name": "Inherited portal review",
        "portalId": "244840437",
        "scope": { "objectTypes": ["0-1", "0-2"] }
      }'
   ```

   The response is `202 Accepted` with the new run:

   ```
   {
      "data" : {
        "id" :  "Xk3p9QwZr2mB7nT1aLc4" ,
        "name" :  "Inherited portal review" ,
        "portalId" :  "244840437" ,
        "portalName" :  "Acme Corp" ,
        "status" :  "PROCESSING" ,
        "progress" : {  "stage" :  "fetching" ,  "percent" :  0  },
        "createdAt" :  "2026-10-14T09:12:44.118Z"
      }
   }
   ```

   Jetstack works out the portal’s name and checks that it belongs to your organization. Organization or portal details you put in the body are ignored. The audit may use AI for naming checks and insights.

2. **Poll until it finishes.**

   Terminal window

   ```
   curl   https://api.jetstack.ai/v1/workflow-audits/Xk3p9QwZr2mB7nT1aLc4   \
      -H   "Authorization: Bearer  $JETSTACK_API_KEY "
   ```

   `progress.stage` moves through `fetching`, `parsing`, `building_graph`, `detecting_conflicts`, `scoring` and `generating_insights`. Stop when `status` is `COMPLETED` or `FAILED`. A completed run also carries `summary`: the workflow count, health score, conflict count, a healthy/warning/critical breakdown and, when the portal has been audited before, the previous score and the change.

   Poll every few seconds rather than in a tight loop. A failed run never turns into an empty report: every results endpoint returns `409` for it.

3. **Read the results.** Start with the summary, then page through what you need.

   Terminal window

   ```
   curl   https://api.jetstack.ai/v1/workflow-audits/Xk3p9QwZr2mB7nT1aLc4/summary   \
      -H   "Authorization: Bearer  $JETSTACK_API_KEY "
   ```

   The summary has the workflow and finding counts, the portfolio score as it was calculated when the audit ran, and coverage: how much of the inventory was captured and whether the analysis and AI steps completed.

To find earlier runs, list them. Filter with `portalId` (the HubSpot portal ID) and `status`, and page with `limit` (1–100, default 25) and `startAfter`: pass the previous page’s `lastId` while `hasMore` is `true`.

Terminal window

```
curl   "https://api.jetstack.ai/v1/workflow-audits?portalId=244840437&status=COMPLETED&limit=10"   \
   -H   "Authorization: Bearer  $JETSTACK_API_KEY "
```

## Page Through Results

The inventory, findings, assets, dependencies, paths and reviews all page the same way:

| Parameter | Default | Limit                                                   |
| --------- | ------- | ------------------------------------------------------- |
| `offset`  | `0`     | Any non-negative integer                                |
| `limit`   | `25`    | `100`                                                   |
| `search`  | none    | 200 characters, case-insensitive, applied before paging |

Each page returns `rows`, `total` (after `search`), `offset` and `nextOffset`. Keep requesting with `offset=nextOffset` until `nextOffset` is `null`. A page is also capped at 512 KiB, so it can hold fewer rows than `limit`. Don’t treat a short page as the end; only a `null` `nextOffset` is.

Every page also carries `auditRunId`, `capturedAt` (when the audit captured the portal), `schemaVersion`, `basis` and `runtimeExecutionAssessed`.

Terminal window

```
curl   "https://api.jetstack.ai/v1/workflow-audits/Xk3p9QwZr2mB7nT1aLc4/findings?limit=50"   \
   -H   "Authorization: Bearer  $JETSTACK_API_KEY "
```

A few things to know about each view:

- **Workflows.** The list leaves out each workflow’s full definition (`snapshot`) and its reference evidence (`references`) to stay compact. `GET .../workflows/{workflowId}` returns both, plus a plain-language brief and the workflow’s health score. Disabled workflows are included.
- **Findings.** Each finding has a `type`, `severity`, the workflows involved, evidence and a recommendation. Add `workflowId` to see only the findings that involve one workflow. A finding’s `fingerprint` stays the same across runs, so you can track it over time.
- **Assets.** Every property, list, form, email, workflow, owner, team and pipeline the workflows reference, with a readable `label` and the number of distinct workflows that use, read and write it. To see the references for one asset, pass its `key` to `GET .../asset?assetKey=`. URL-encode the key exactly as returned. Keys include the object type, so a property with the same name on contacts and on companies stays separate.
- **Reviews.** Add `workflowId` to see the reviews for one workflow, including dispositions of findings that involve it.

If a single item is larger than 512 KiB, the request returns `413`. The item hasn’t been dropped. Read it through the workflow detail or the full result instead.

## Dependencies and Enrollment Paths

`GET .../workflows/{workflowId}/dependencies` returns the direct relationships between one workflow and others. Each connection names its `relationship` and carries the evidence behind it: the workflow, the kind of reference, where it was found (`surface`, `locator`) and the action ID where one was captured. Filter with `relationship`:

| Relationship          | Meaning                                                                                                                                       |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `explicit-enrollment` | An action in one workflow enrolls records into another. This shows how they are configured, not that records are eligible or that it ran.     |
| `potential-handoff`   | One workflow writes a property that another reads on the same object. Whether the same records, conditions and timing line up is not checked. |
| `shared-writer`       | Both workflows write the same property. This is not a conflict by itself.                                                                     |
| `shared-usage`        | Both workflows use the same asset, with no direction between them.                                                                            |

`GET .../workflows/{workflowId}/paths` follows `explicit-enrollment` links only. Filter with `direction=upstream` (workflows that lead into this one) or `direction=downstream` (workflows this one leads to). For each workflow it can reach, you get one shortest path per direction, up to 20 steps. A path with `cycle: true` is one example that loops back to the selected workflow, not every loop in the portal.

Both responses include `coverage`: workflows that are referenced but missing from the captured inventory, whether the analysis is complete, and `pathsTruncated` when the 20-step limit was reached. Coverage describes the captured inventory. Missing targets, custom code, webhooks and incomplete definitions stay visible as unknowns rather than being left out.

## Save Reviews

Reviews let your team record what it decided about a workflow or a finding. They belong to the portal, not to one run, so they carry over to the next audit of the same portal. They never change the audit’s evidence, its scores or anything in HubSpot.

There are three kinds:

| `kind`     | `entityId`                  | Other fields                                                                   |
| ---------- | --------------------------- | ------------------------------------------------------------------------------ |
| `note`     | A workflow `id`             | `text`, required for a new note                                                |
| `finding`  | The finding’s `fingerprint` | `status`: `open`, `resolved` or `ignored`. `text` is optional.                 |
| `decision` | A workflow `id`             | `decision`, `decisionStatus`, `owner` and a rationale in `text` (all required) |

Decisions are `keep`, `improve`, `investigate` or `retirement-candidate`. `decisionStatus` is `proposed` or `agreed`. It records where your team’s review stands; it doesn’t approve any change. `owner` is a label of up to 200 characters; send an empty string for no owner. `text` can be up to 8,000 characters. A decision never approves deleting a workflow.

Terminal window

```
curl   -X   PUT   https://api.jetstack.ai/v1/workflow-audits/Xk3p9QwZr2mB7nT1aLc4/reviews   \
   -H   "Authorization: Bearer  $JETSTACK_API_KEY "   \
   -H   "Content-Type: application/json"   \
   -d   '{
     "kind": "decision",
     "entityId": "4924872395",
     "decision": "investigate",
     "owner": "Sales operations",
     "decisionStatus": "proposed",
     "text": "Check seasonal use and downstream dependencies with the owner.",
     "expectedVersion": 0
   }'
```

The response is the saved entry with its new `version`.

**Versions protect concurrent edits.** Send `expectedVersion: 0` only when creating an entry. After that, send the last `version` you received. If someone else saved in between, the request returns `409` and nothing is overwritten. Read the reviews again and retry.

Only completed audits can be annotated, and only workflows and findings analysed by the current audit engine are valid targets. An unknown target returns `400`.

When you read reviews, two fields tell you what has changed since a review was saved:

- A finding marked `resolved` that shows up again in a later run comes back with `reopened: true` and `effectiveStatus: "open"`. Your saved disposition is kept.
- A decision has `needsRevalidation: true` when the workflow’s definition in this run differs from the one that was reviewed, or can’t be compared.

## Export Large Audits

For a complete export, you have two options:

- **`GET .../evidence?kind=…`** reads stored evidence one kind at a time: `workflow`, `finding`, `node`, `edge`, `cluster`, `score` or `insight`. Pages hold up to 20 items (`limit`, default 20) and follow the same `offset` and `nextOffset` pattern. Any item over 64 KiB comes back as a `requires-detail` marker with its size, so you know to fetch it through the workflow detail or the full result. `snapshotId` identifies the stored snapshot the page came from.
- **`GET .../result`** returns the whole report in one response: every workflow with its definition, the dependency graph, findings, health scores, the portfolio score and insights, plus the portal’s current reviews and a benchmark against other portals your organization has audited. On large portals this response is big; prefer the paginated endpoints or `/evidence`.

Audits from before indexed evidence was introduced return `409` with `WORKFLOW_AUDIT_RESULT_NOT_FOUND` from `/evidence`. Use `/result` for those.

## Retries and Idempotency

Send an `Idempotency-Key` header (a UUID is a good choice, up to 256 characters) when you start an audit. That makes a retry safe:

- The key is reserved for 24 hours and bound to the request body.
- The first response, success or error, is saved. A retry with the same key and body gets that response back with `Idempotent-Replayed: true`, and no second scan starts.
- Reusing the key with a different body returns `409`. So does retrying while the first request is still running, or if its outcome is unknown. In that case, list your audits to see whether the run was created before you start a new one with a fresh key.
- A replay still needs a key that carries `audit:write`.

If you correct a mistake in the body after an error, use a new key.

## Errors

Errors are [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem documents sent as `application/problem+json`, with a stable `code` and a `requestId`. Match on `code`, not on the wording of `detail`.

```
{
   "type" :  "https://api.jetstack.ai/errors/workflow-audit-run-invalid-status" ,
   "title" :  "Invalid Workflow Audit Status" ,
   "status" :  409 ,
   "detail" :  "Audit results are not yet published" ,
   "instance" :  "/v1/workflow-audits/Xk3p9QwZr2mB7nT1aLc4/summary" ,
   "code" :  "WORKFLOW_AUDIT_RUN_INVALID_STATUS" ,
   "requestId" :  "req_7f3a9c2e"
}
```

| Status | Code                                                                                                  | When                                                                                      |
| ------ | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `400`  | `API_INVALID_INPUT`                                                                                   | A missing or invalid field or query parameter, or a review target that isn’t in the audit |
| `400`  | `WORKFLOW_AUDIT_HUBSPOT_FETCH_FAILED`                                                                 | The portal’s HubSpot connection is missing the `automation` scope                         |
| `401`  | `AUTH_TOKEN_MISSING`, `AUTH_TOKEN_INVALID`, `API_KEY_NOT_FOUND`, `API_KEY_REVOKED`, `API_KEY_EXPIRED` | The API key is missing, malformed, unknown, revoked or expired                            |
| `403`  | `API_KEY_INSUFFICIENT_SCOPE`                                                                          | The key doesn’t carry `audit:read` or `audit:write`                                       |
| `403`  | `WORKFLOW_AUDIT_RUN_ACCESS_DENIED`                                                                    | The run belongs to another organization (run status and full result)                      |
| `404`  | `WORKFLOW_AUDIT_RUN_NOT_FOUND`                                                                        | No such run in your organization                                                          |
| `404`  | `PORTAL_NOT_FOUND`                                                                                    | The portal isn’t connected to your organization                                           |
| `404`  | `WORKFLOW_AUDIT_RESULT_NOT_FOUND`                                                                     | The run completed but has no stored result                                                |
| `404`  | `API_INVALID_INPUT`                                                                                   | The workflow or asset you asked for isn’t in this audit                                   |
| `404`  | `REST_API_NOT_FOUND`                                                                                  | Not a workflow audit route: wrong path, trailing slash or unsupported method              |
| `409`  | `WORKFLOW_AUDIT_RUN_INVALID_STATUS`                                                                   | The run hasn’t completed, so results and reviews aren’t available yet                     |
| `409`  | `API_INVALID_INPUT`                                                                                   | An idempotency key conflict, or a review `expectedVersion` that is out of date            |
| `409`  | `WORKFLOW_AUDIT_RESULT_NOT_FOUND`                                                                     | `/evidence` on an older audit; use `/result`                                              |
| `413`  | `API_INVALID_INPUT`                                                                                   | A single item is over the 512 KiB page budget                                             |
| `429`  | `API_KEY_RATE_LIMITED`                                                                                | Rate limit reached; wait for the seconds in `Retry-After`                                 |
| `500`  | `API_INTERNAL_ERROR`                                                                                  | Something went wrong on our side; contact support with the `requestId` if it persists     |

## What the API Doesn’t Do

- It doesn’t change HubSpot. There is no endpoint to enable, disable, edit or delete a workflow.
- It doesn’t report execution history, verified last-run times or proof that a workflow is unused, and it doesn’t say whether a workflow is safe to retire. Use the brief, dependencies and findings to guide that conversation with the portal owner.
- Scheduling audits, PDF export and the audit chat are not available over the API.

## Next Steps

[API reference ](https://jetstack.ai/api)Every endpoint, parameter and response schema, with a request builder.

[Authentication ](https://jetstack.ai/docs/developers/authentication)API keys, scopes, instance routing and rate limits.

[Understanding results ](https://jetstack.ai/docs/audits/workflow-audits/results)How to read health scores, findings and dependency maps.

[Workflow Audit Overview ](https://jetstack.ai/docs/audits/workflow-audits/overview)What a workflow audit checks and when to run one.
