WorkflowsVersion: v3

Get Workflow Logs

GET/workflows/{workflowId}/logs

Limited availability. The workflow API is currently enabled for selected sub-accounts only; any other sub-account receives 403 WORKFLOW_API_NOT_ENABLED_FOR_LOCATION.

List the step-by-step execution history of one workflow, newest first. Each record is one step of one run for one contact or record, with its outcome and timing. It answers who and what: who entered, what happened to a contact, which steps failed and for whom. To answer how many, use Get Workflow Log Statistics.

Before you call it. Get workflowId from Search Workflows. Never pass a workflow name. To see what each step is, call Get Workflow Definition: its actions[].id matches stepId here.

Step details. meta says how the contact entered, why a step was skipped or failed, what a step did, whether a wait timed out, and why the contact left. A key is left out when it does not apply. Only the keys documented under meta are returned. New keys may be added later (see Compatibility).

Paging. The response holds logs, their count, and nextCursor. The first call (action=first, the default) returns the newest page. For the next (older) page, send action=next with referenceId and referenceCreatedAt from nextCursor, unchanged, and keep the same filters and dates. nextCursor is null when there are no more records. A cursor that does not match returns 422. A page holds at most 100 records, 15 by default.

Dates. Send startDate and endDate together (ISO 8601, UTC, at most 30 days apart). Without them, the last 30 days are returned. Logs are available for the last 60 days.

Common questions.

Who entered the workflow: statuses=added_to_workflow
Which steps failed, and for whom: statuses=error,failed,failed_retry_limit_reached
What happened to one contact: contactId=<contact ID>
Every step of one run: executionId=<workflowStatusId of any record from that run>

An empty logs list is a real answer: nothing matched in that window. A workflowId that does not exist in the sub-account, or is a folder, returns 404.

Compatibility. New optional fields, including new meta keys, and new values of status, type and recordType can appear at any time. Ignore fields you do not know, and treat an unknown value as other.

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your access token.

Scope:workflows.logs

Auth methods:OAuthPrivate Integration

Token type:Sub-Account Token

Request

Headers

Versionstringrequired

API Version. Send v3.

Available optionsv3

Example:v3

Path Parameters

workflowIdstringrequired

Workflow ID. Get it from Search Workflows. Never pass a workflow name

Example:a7321e66-8b68-4c10-afc7-4cc9744f17af

Query Parameters

locationIdstringrequired

Sub-account (location) ID. It must be the sub-account the token belongs to, otherwise the request is refused with 403

Example:ve9EPM428h8vShlRW1KT

limitnumber

Records per page, 1 to 100. Default 15

Example:20

actionstring

first returns the newest page, which can also start with steps that are still running. next returns the next (older) page, starting at the record in nextCursor, and requires referenceId and referenceCreatedAt. Defaults to first

Available optionsfirstnext

Example:first

referenceIdstring

nextCursor.referenceId from the previous response. Required with next

Example:0123456789abcdef01234567

referenceCreatedAtstring

nextCursor.referenceCreatedAt from the previous response, sent unchanged. Required with next

Example:2026-09-25T10:00:00.000Z

typesstring[]

Only steps of this type: a step type key, as listed by Get Step Types or in actions[].type of Get Workflow Definition, for example email. One type per call on this route. drip also matches drip_queued and drip_resume, and if_else also matches condition. New values can appear

Example:["email"]

statusesstring[]

Only steps with these outcomes (the status field). Repeat the parameter or send a comma-separated list. Values: added_to_workflow (the contact entered the workflow), success (the step ran), error and failed (the step did not complete), failed_retry_limit_reached (the step gave up after its retries), retry (the step will run again), skipped (the step did not run, for example because of DND, a time window or missing data), waiting (the contact is waiting at the step), wait_finished (a wait ended), finished (the contact left the workflow, see removedReason), paused_due_to_draft_mode (the workflow was unpublished while the contact was in it), contact_merged (the contact was merged into another contact), drip_queued (the contact is waiting in a drip step for its batch), drip_resume (the batch was released and the contact moved on), processing (the step has started and has not finished yet), and winner_declared (an A/B test step picked its winning path; the record has no contact). For every kind of failure, send error, failed and failed_retry_limit_reached. New values can appear

Example:["error","failed"]

startDatestring

Start of the range, ISO 8601: a plain date (start of that day, UTC) or a full timestamp. Send it together with endDate. Defaults to 30 days ago. Logs are available for the last 60 days, so it cannot be earlier than that

Example:2026-06-01

endDatestring

End of the range, ISO 8601. A plain date includes the whole day. At most 30 days after startDate. Defaults to now

Example:2026-06-30

contactIdstring

Only logs for this contact. Use the contactId of a record

Example:exampleContactId0001

executionIdstring

Only the steps of one execution: one run of the workflow for one contact or record. Use the workflowStatusId of any record from that run

Example:01ARZ3NDEKTSV4RRFFQ69G5FAV

recordIdstring

Only logs for one record, in workflows that run on records (opportunities, custom objects and so on) instead of contacts. Use the recordId of a record. Send it with recordType

Example:exampleRecordId00001

recordTypestring

Object type of recordId. Use the recordType of the same record. Values: contact, opportunity, task, business, inbound_webhook, or custom_objects.<object key> for a custom object, for example custom_objects.cars. New values can appear

Example:opportunity

Response

application/json

Successful response

countnumberrequired

Number of records in this response

Example:15

nextCursorobjectnullablerequired

Where the next (older) page starts: send action=next with these values and the same filters and dates. Null when there are no more records

logsobject[]required

The records, newest first

logs[].idstringrequired

ID of this log record

Example:0123456789abcdef01234567

logs[].locationIdstringrequired

Sub-account (location) that owns the workflow

Example:ve9EPM428h8vShlRW1KT

logs[].workflowIdstringrequired

Workflow that produced this record

Example:a7321e66-8b68-4c10-afc7-4cc9744f17af

logs[].contactIdstring

Contact the step ran for. Empty string when the step did not run for a contact

Example:exampleContactId0001

logs[].workflowStatusIdstring

Execution ID. Every step of one run shares it. Send it as executionId to read that run only

Example:01ARZ3NDEKTSV4RRFFQ69G5FAV

logs[].stepIdstringnullable

Step ID. Matches actions[].id in Get Workflow Definition. Group by it in Get Workflow Log Statistics. On if/else steps where attributes.version is 2, it is the ID of the branch that was taken, not the if/else step's ID, and stepName is that branch's name. To find the branch in Get Workflow Definition, match stepName to the if/else step's attributes.branches[].name, or to attributes.noneBranchName when no branch matched. Can be null

Example:123e4567-e89b-12d3-a456-426614174000

logs[].stepNamestring

Step name as shown in the builder when the step ran. On if/else steps where attributes.version is 2, it is the name of the branch that was taken

Example:Update Custom Value

logs[].typestringrequired

Step type key, the same key Get Step Types and Get Workflow Definition use, with these exceptions: if/else steps are logged as condition, wait steps as wait_time, wait_reply and similar, and drip steps as drip, drip_queued or drip_resume. Some records are not steps, for example added_to_workflow when a contact enters and remove_from_workflow when a contact leaves. Send it in types to filter. New values can appear

Example:update_custom_value

logs[].statusstringrequired

Outcome of the step: added_to_workflow (the contact entered the workflow), success (the step ran), error and failed (the step did not complete), failed_retry_limit_reached (the step gave up after its retries), retry (the step will run again), skipped (the step did not run, for example because of DND, a time window or missing data), waiting (the contact is waiting at the step), wait_finished (a wait ended), finished (the contact left the workflow, see removedReason), paused_due_to_draft_mode (the workflow was unpublished while the contact was in it), contact_merged (the contact was merged into another contact), drip_queued (the contact is waiting in a drip step for its batch), drip_resume (the batch was released and the contact moved on), processing (the step has started and has not finished yet), and winner_declared (an A/B test step picked its winning path; the record has no contact). New values can appear

Example:success

logs[].recordIdstringnullable

Record the step ran for, in workflows that run on records. Null otherwise

Example:exampleRecordId00001

logs[].recordTypestringnullable

Object type of recordId: contact, opportunity, task, business, inbound_webhook, or custom_objects.<object key> for a custom object, for example custom_objects.cars. New values can appear

Example:opportunity

logs[].recordPrimaryPropertystringnullable

Display name of the record

Example:Acme renewal

logs[].contactNamestringnullable

Contact name when the step ran

Example:Alex Doe

logs[].contactEmailstringnullable

Contact email when the step ran

Example:[email protected]

logs[].metaobjectrequired

Step details. Which keys appear depends on the step type and outcome, and a key is left out when it does not apply. Only the keys documented here are returned. New keys may be added later

logs[].createdAtstringrequired

When the step was logged