GET /rest/v2.0/companies/{company_id}/workflows/instances/{id}/history

Returns an ordered list of history events for a given company workflow instance.

Each event in the history array has a type field and a details object. The following event types are supported:

WorkflowStarted — emitted when the workflow begins.

{
  "type": "WorkflowStarted",
  "details": {
    "started_at": "2024-01-15T10:00:00Z"
  }
}

WorkflowTerminated — emitted when the workflow is terminated before completion.

{
  "type": "WorkflowTerminated",
  "details": {
    "name": "Bulk Assignee Update",
    "terminated_at": "2024-01-15T10:30:00Z",
    "terminated_by": {
      "id": "77",
      "login": "mary@example.com",
      "name": "Mary Thompson"
    },
    "terminate_reason": "Suspended",
    "terminate_result": {
      "details": [
        {
          "items": [
            {
              "label": "Status",
              "text": "Approved"
            }
          ]
        }
      ]
    }
  }
}

ResponseStep — emitted for each response step, including who responded and what they said.

{
  "type": "ResponseStep",
  "details": {
    "id": "1001",
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Manager Approval",
    "started_at": "2024-01-15T10:00:00Z",
    "ended_at": "2024-01-15T11:00:00Z",
    "due_date": "2024-01-16T17:00:00Z",
    "decision_type": "first",
    "required_responders_decide": true,
    "responses": [
      {
        "id": "12345",
        "response_id": "99901",
        "login": "mary@example.com",
        "name": "Mary Thompson",
        "response": "Approved",
        "response_type": "approve",
        "required": true,
        "comment": "Looks good to me.",
        "responded_at": "2024-01-15T10:45:00Z",
        "attachments": [
          {
            "name": "review.pdf",
            "url": "https://example.com/review.pdf"
          }
        ],
        "original_assignees": [
          {
            "id": "67890",
            "name": "John Smith",
            "login": "john@example.com"
          }
        ]
      }
    ],
    "overall_response": "Approved",
    "overall_response_type": "approve",
    "overall_response_description": "All required approvers agreed.",
    "status": "Approved",
    "available_response_options": null,
    "events": [
      {
        "type": "action_executed",
        "title": "Action Executed",
        "created_at": "2024-01-15T10:05:00Z",
        "created_by": {
          "id": "100",
          "login": "automation@example.com",
          "name": "Workflow System"
        },
        "icon": "People",
        "temporary": false,
        "details": [
          {
            "type": "custom",
            "title": "Watermark applied",
            "icon": "Document",
            "created_by": {
              "id": "100",
              "login": "automation@example.com",
              "name": "Workflow System"
            },
            "items": [
              {
                "label": "Document",
                "text": "Spec v2"
              }
            ]
          }
        ]
      }
    ],
    "assignee_updates": [
      {
        "created_at": "2024-01-15T10:12:00Z",
        "created_by": {
          "id": "200",
          "login": "coordinator@example.com",
          "name": "Pat Coordinator"
        },
        "logins": [
          {
            "id": "12345",
            "name": "Mary Thompson",
            "login": "mary@example.com",
            "required": true
          }
        ],
        "roles": [
          {
            "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "responses_required": "all"
          }
        ]
      }
    ],
    "roles": [
      {
        "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "name": "Project Manager",
        "type": "project_role",
        "responses_required": "one",
        "login_ids": ["12345"]
      }
    ],
    "additional_assignees": [
      {
        "required": true,
        "invited_by": {
          "id": "200",
          "login": "coordinator@example.com",
          "name": "Pat Coordinator"
        },
        "logins": [
          {
            "id": "50001",
            "login": "newhire@example.com",
            "name": "New Hire"
          }
        ],
        "created_at": "2024-01-15T10:20:00Z",
        "reason": "new_employee",
        "comment": null
      }
    ],
    "individual_assignees": [
      {
        "id": "50002",
        "name": "Alex Lee",
        "login": "alex@example.com",
        "required": true
      }
    ],
    "notification_recipients": [
      {
        "id": "300",
        "name": "Sam Observer",
        "login": "sam@example.com"
      }
    ]
  }
}

EndStep — emitted when the workflow reaches a terminal step (either successful completion or termination).

{
  "type": "EndStep",
  "details": {
    "id": "2001",
    "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "Complete",
    "started_at": "2024-01-15T11:00:00Z",
    "ended_at": "2024-01-15T11:00:01Z",
    "due_date": "2024-01-16T12:00:00Z",
    "end_type": "success",
    "status": "Approved"
  }
}

Action — emitted for automated action steps (e.g. setting a status via a dynamic step).

{
  "type": "Action",
  "details": {
    "id": "3001",
    "uuid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "name": "Set Status",
    "started_at": "2024-01-15T11:00:00Z",
    "ended_at": "2024-01-15T11:00:01Z",
    "due_date": null,
    "description": "Contract status updated to Approved"
  }
}

Conditional — emitted when a conditional gateway is evaluated.

{
  "type": "Conditional",
  "details": {
    "id": "4001",
    "uuid": "d4e5f6a7-b8c9-0123-def0-234567890123",
    "name": "Amount > 50?",
    "evaluated_at": "2024-01-15T11:00:00Z",
    "description": "Amount is greater than 50: Yes"
  }
}

Servers

https://api.procore.com

Path parameters

Name	Type	Required	Description
`id`	String	Yes	Unique identifier for the workflow instance.
`company_id`	String	Yes	Unique identifier for the company.

Request headers

Name	Type	Required	Description
`Procore-Company-Id`	Integer	Yes	Unique company identifier associated with the Procore User Account.

Query parameters

Name	Type	Required	Description
`filters[activity_types][][]`	Array	No	Optional activity filter (`comments`, `attachments`). When present, the response only includes timeline rows that match the filter. Future step events are not included when this filter is used (linear templates only).

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.