Skip to content

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. Every endpoint, parameter and response schema is in the interactive API reference.

  • 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 for key management, scopes and rate limits.

The examples below assume:

Terminal window
export JETSTACK_API_KEY="jsai_your_api_key"

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

MethodPathScopeWhat it does
POST/v1/workflow-auditsaudit:writeStart an audit
GET/v1/workflow-auditsaudit:readList runs, newest first
GET/v1/workflow-audits/{runId}audit:readStatus, progress and headline numbers
GET/v1/workflow-audits/{runId}/summaryaudit:readTotals, portfolio score and coverage
GET/v1/workflow-audits/{runId}/workflowsaudit:readThe workflow inventory, paginated and searchable
GET/v1/workflow-audits/{runId}/workflows/{workflowId}audit:readOne workflow in full, with a plain-language brief and its score
GET/v1/workflow-audits/{runId}/workflows/{workflowId}/dependenciesaudit:readDirect relationships, with evidence
GET/v1/workflow-audits/{runId}/workflows/{workflowId}/pathsaudit:readUpstream and downstream enrollment paths
GET/v1/workflow-audits/{runId}/assetsaudit:readEvery referenced asset, with reader and writer counts
GET/v1/workflow-audits/{runId}/asset?assetKey=…audit:readThe workflow references for one asset
GET/v1/workflow-audits/{runId}/findingsaudit:readConfiguration findings
GET/v1/workflow-audits/{runId}/reviewsaudit:readNotes, finding dispositions and decisions
PUT/v1/workflow-audits/{runId}/reviewsaudit:writeSave a note, disposition or decision
GET/v1/workflow-audits/{runId}/evidence?kind=…audit:readBounded pages of stored evidence
GET/v1/workflow-audits/{runId}/resultaudit:readThe 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.

  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"

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

ParameterDefaultLimit
offset0Any non-negative integer
limit25100
searchnone200 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.

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:

RelationshipMeaning
explicit-enrollmentAn action in one workflow enrolls records into another. This shows how they are configured, not that records are eligible or that it ran.
potential-handoffOne workflow writes a property that another reads on the same object. Whether the same records, conditions and timing line up is not checked.
shared-writerBoth workflows write the same property. This is not a conflict by itself.
shared-usageBoth 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.

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:

kindentityIdOther fields
noteA workflow idtext, required for a new note
findingThe finding’s fingerprintstatus: open, resolved or ignored. text is optional.
decisionA workflow iddecision, 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.

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.

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 are RFC 7807 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"
}
StatusCodeWhen
400API_INVALID_INPUTA missing or invalid field or query parameter, or a review target that isn’t in the audit
400WORKFLOW_AUDIT_HUBSPOT_FETCH_FAILEDThe portal’s HubSpot connection is missing the automation scope
401AUTH_TOKEN_MISSING, AUTH_TOKEN_INVALID, API_KEY_NOT_FOUND, API_KEY_REVOKED, API_KEY_EXPIREDThe API key is missing, malformed, unknown, revoked or expired
403API_KEY_INSUFFICIENT_SCOPEThe key doesn’t carry audit:read or audit:write
403WORKFLOW_AUDIT_RUN_ACCESS_DENIEDThe run belongs to another organization (run status and full result)
404WORKFLOW_AUDIT_RUN_NOT_FOUNDNo such run in your organization
404PORTAL_NOT_FOUNDThe portal isn’t connected to your organization
404WORKFLOW_AUDIT_RESULT_NOT_FOUNDThe run completed but has no stored result
404API_INVALID_INPUTThe workflow or asset you asked for isn’t in this audit
404REST_API_NOT_FOUNDNot a workflow audit route: wrong path, trailing slash or unsupported method
409WORKFLOW_AUDIT_RUN_INVALID_STATUSThe run hasn’t completed, so results and reviews aren’t available yet
409API_INVALID_INPUTAn idempotency key conflict, or a review expectedVersion that is out of date
409WORKFLOW_AUDIT_RESULT_NOT_FOUND/evidence on an older audit; use /result
413API_INVALID_INPUTA single item is over the 512 KiB page budget
429API_KEY_RATE_LIMITEDRate limit reached; wait for the seconds in Retry-After
500API_INTERNAL_ERRORSomething went wrong on our side; contact support with the requestId if it persists
  • 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.