# Executing workflows

Linked API is built around the **concept of workflows**. This means that any automation you want to perform (such as sending a connection request, commenting on a post, retrieving company data, etc.) must be executed as a workflow.

> For details on how to build workflows, visit the [building workflows](/docs/building-workflows) page.

Executing a workflow consists of 2 key steps:

1. Starting a workflow and receiving its `workflowId`, current `workflowStatus`, and human-readable `message`.
2. Periodically checking for the result using the `workflowId`.

## Starting workflows

To start executing a workflow, make a `POST` request to the following endpoint:

```text
POST https://api.linkedapi.io/workflows
```

In the request body, include a JSON that describes your workflow, for example:

```json
{
  "actionType": "st.checkConnectionStatus",
  "personUrl": "https://www.linkedin.com/in/person1"
}
```

Upon successful request, you will receive the following response:

```json
{
  "success": true,
  "result": {
    "workflowId": "wf-64835e7c-a0gc-40ae-8338-108f02sSe643",
    "workflowStatus": "pending",
    "pendingReason": "queued",
    "message": "This workflow is scheduled and will start after 2 other workflows already scheduled ahead of it."
  }
}
```

- `workflowId` – unique workflow identifier for checking the result.
- `workflowStatus` – current workflow status. Possible values at start are `pending` and `running`.
- `pendingReason` – why the workflow has not started yet. `queued` means it is waiting its turn behind other work on the same account; `outsideWorkingHours` means it is parked until the account [working hours](/docs/working-hours) reopen. It is `null` once the workflow is no longer pending.
- `message` – human-readable execution message, such as queue position or estimated duration. This value can change while polling.

In case of an unsuccessful request, you will receive the following response:

```json
{
  "success": false,
  "error": {
    "type": "linkedApiTokenRequired",
    "message": "'linked-api-token' is missing in request headers."
  }
}
```

- `error` – either a [common error](/docs/making-requests) or one of the following specific errors:
  - `invalidWorkflow` – workflow configuration is not valid due to violated [action constraints](/docs/actions-overview) or invalid [action parameters](/docs/actions-overview): `{validation_details}`.
  - `outsideWorkingHours` – the account is outside its configured [working hours](/docs/working-hours) and its off-hours policy is set to reject. Nothing is queued.

## Checking for result

> Prefer to be notified instead of polling? Register a [webhook](/docs/webhooks) and Linked API will `POST` an event to your endpoint when the workflow completes.

After starting your workflow and receiving the `workflowId`, you need to periodically check the workflow result. To do this, send a `GET` request to the following endpoint:

```text
GET https://api.linkedapi.io/workflows/{workflowId}
```

Depending on the workflow execution status, you'll receive one of these results:

1. **Workflow is pending (queued for execution):**

```json
{
  "success": true,
  "result": {
    "workflowStatus": "pending",
    "pendingReason": "queued",
    "message": "This workflow is scheduled and will start after 2 other workflows already scheduled ahead of it."
  }
}
```

Workflows are executed sequentially per LinkedIn account. If you submit multiple workflows, the first one starts executing immediately while the others are queued. The `pending` status means the workflow is waiting in the queue and will start running once the previous workflows complete.

A workflow can also be pending because the account is outside its [working hours](/docs/working-hours). In that case `pendingReason` is `outsideWorkingHours` and the workflow will not move until the window reopens, which can be the next working day:

```json
{
  "success": true,
  "result": {
    "workflowStatus": "pending",
    "pendingReason": "outsideWorkingHours",
    "message": "This workflow is scheduled and will start when the account working hours open at Mon, Aug 10, 09:00 (Europe/Berlin)."
  }
}
```

Back off your polling in that case rather than retrying every few seconds – the `message` names the time the window opens.

2. **Workflow is running:**

```json
{
  "success": true,
  "result": {
    "workflowStatus": "running",
    "pendingReason": null,
    "message": "This workflow usually takes about 30-60 seconds."
  }
}
```

While a workflow is `pending` or `running`, the `message` field may update between polling requests. For example, a queued workflow can first return a queue-position message and later return an estimated-duration message after it starts running.

3. **Workflow completed successfully:**

```json
{
  "success": true,
  "result": {
    "workflowStatus": "completed",
    "completion": {
      "actionType": "st.checkConnectionStatus",
      "success": true,
      "data": {
        "connectionStatus": "pending"
      }
    }
  }
}
```

- `completion` – results of all actions included in this workflow.

4. **Workflow completed with action error:**

```json
{
  "success": true,
  "result": {
    "workflowStatus": "completed",
    "completion": {
      "actionType": "st.checkConnectionStatus",
      "success": false,
      "error": {
        "type": "limitExceeded",
        "message": "The configured limit for this action category has been exceeded."
      }
    }
  }
}
```

5. **Workflow failed:**

```json
{
  "success": true,
  "result": {
    "workflowStatus": "failed",
    "failure": {
      "reason": "linkedinAccountSignedOut",
      "message": "This LinkedIn account has been signed out in our cloud browser."
    }
  }
}
```

- `failure` – object describing the workflow failure reason:
  - `linkedinAccountSignedOut` – your LinkedIn account has been signed out in our cloud browser. This occasionally happens as LinkedIn may sign out accounts after an extended period. You'll need to visit [our platform](https://app.linkedapi.io/) and reconnect your account.
  - `languageNotSupported` – your LinkedIn account uses a language other than English, which is currently the only supported option. If you encounter this issue, please contact our support. We prioritize adding new languages based on user requests, so your feedback is important.

> In case of an unsuccessful request, you'll receive one of the [common errors](/docs/making-requests).

## Cancelling workflows

Some workflows in Linked API can take a long time to complete. If you decide you no longer need a workflow to finish, you have the option to cancel it.

You can cancel a running or pending workflow directly on [our platform](https://app.linkedapi.io/stats). Simply click the three dots menu next to the workflow and select "Cancel".

Alternatively, you can cancel a workflow via API. To do this, you need to make a `DELETE` request to the following endpoint:

```text
DELETE https://api.linkedapi.io/workflows/{workflowId}
```

Upon successful cancellation, you will receive the following response:

```json
{
  "success": true,
  "result": {
    "cancelled": true
  }
}
```

> In case of an unsuccessful request, you'll receive one of the [common errors](/docs/making-requests).

**Important notes:**

- **Partial execution.** The workflow is cancelled at its current execution point. Any actions that have already been completed cannot be undone. For example, if the workflow has already sent messages or connection requests from your LinkedIn account, these actions will remain executed.
- **No intermediate data.** Once a workflow is cancelled, no data is preserved or returned. You will not receive any intermediate results or partial data that may have been collected before cancellation.