# Executing workflows

How to execute a workflow: start it, check for its result and cancel it – with request and response formats and the errors of each step.

> The API Reference is also the SDK and CLI reference. Consecutive code fences marked `tab=HTTP`, `tab=Node`, `tab=Python` and `tab=CLI` are the same call on each surface (a fence marked `tab=HTTP,CLI` is the same text for both), and a block between `:::surface <names>` and `:::` applies only to the surfaces it names. Identifiers in the text are written as in Node and in HTTP JSON (camelCase); the Python SDK spells methods, parameters and result attributes in snake_case (`sendMessage` → `send_message`, `reconnectionLink` → `reconnection_link`), while names inside HTTP JSON stay camelCase.

> 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

:::surface http
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:
:::

:::surface node,python,cli
Start the workflow with the request it should run, for example:
:::

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

```typescript tab=Node
const workflow = await linkedapi.checkConnectionStatus.execute({
  personUrl: "https://www.linkedin.com/in/person1",
});

console.log(workflow.workflowId);
```

```python tab=Python
from linkedapi import CheckConnectionStatusParams

workflow = linkedapi.check_connection_status.execute(
    CheckConnectionStatusParams(person_url="https://www.linkedin.com/in/person1")
)

print(workflow.workflow_id)
```

```bash tab=CLI
linkedin workflow run <<'JSON'
{
  "actionType": "st.checkConnectionStatus",
  "personUrl": "https://www.linkedin.com/in/person1"
}
JSON
```

:::surface node,python
Every SDK method has `execute()`, which starts the workflow and returns its `workflowId`; any workflow JSON goes through [`customWorkflow`](/sdks/custom-workflow). See [Predefined vs Custom Workflows](/sdks/predefined-vs-custom).
:::

:::surface cli
Commands such as `linkedin connection status` start the workflow and wait for its result, and so does `linkedin workflow run` for any workflow JSON – see [Custom Workflows](/cli/workflows). The CLI has no separate start step: while it waits it writes the workflow ID and status to stderr as progress (hidden by `--quiet`), and at the end it prints the completion as `data`. The response below is what the API returns to the start request.
:::

:::surface http
Upon successful request, you will receive the following response:
:::

:::surface node,python
**Under the hood** – `execute()` sends this request and returns the fields of its `result` directly: `workflowId`, `workflowStatus`, `pendingReason` and `message` (`workflow_id`, `workflow_status`, `pending_reason` and `message` in Python), without the `success` and `result` wrapper:
:::

```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.

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

:::surface node,python
**Errors** – an unsuccessful start throws `LinkedApiError` with the `type` and `message` of this response:
:::

:::surface cli
**Errors** – the CLI prints an unsuccessful start to stderr as `{"error": "<type>", "message": "…"}` and exits with the matching [exit code](/cli/flags-and-output#exit-codes). The types are the ones below:
:::

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

- `error` – either a [common error](/docs/common-errors) 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), including a parameter the root action does not define: `{validation_details}`.
  - `subscriptionRequired` – no purchased subscription seats are available for this LinkedIn account (message: `No purchased subscription seats available for this LinkedIn account.`). Add seats, renew the subscription for existing seats, or check for payment issues on the [platform](https://app.linkedapi.io/).
  - `plusPlanRequired` – the workflow contains Sales Navigator actions (`nv.*`) or [Recruiter Lite](/docs/recruiter-lite-overview) actions (`rc.*`). They need a Plus seat, and the LinkedIn account needs the matching Sales Navigator or Recruiter Lite subscription.
  - `linkedinAccountSignedOut` – the LinkedIn account has been signed out in our cloud browser. Reconnect it on the [platform](https://app.linkedapi.io/).
  - `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:

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

```typescript tab=Node
// Waits until the workflow completes
const { data, errors } = await linkedapi.checkConnectionStatus.result(workflowId);

// Checks once, without waiting
const status = await linkedapi.checkConnectionStatus.status(workflowId);
```

```python tab=Python
# Waits until the workflow completes
result = linkedapi.check_connection_status.result(workflow_id)

# Checks once, without waiting
status = linkedapi.check_connection_status.status(workflow_id)
```

```bash tab=CLI
# Check the current status
linkedin workflow status abc123

# Wait for completion
linkedin workflow status abc123 --wait --json
```

:::surface node,python
`result()` polls for you and returns `{ data, errors }` once the workflow completes; `status()` checks once. How the SDK reports workflow and request errors is described in [Handling Results and Errors](/sdks/handling-results).
:::

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

:::surface node,python
**Under the hood** – while the workflow is pending or running, `status()` returns its `workflowStatus`, `pendingReason` and `message`. Once it completes, `status()` and `result()` return the method's own `{ data, errors }` mapped from the completion, not the response itself. A failed workflow throws `LinkedApiError` whose `type` is the `failure.reason` below. These are the API responses they read:
:::

:::surface cli
**Output** – while the workflow is pending or running, `linkedin workflow status` prints `{"success": true, "data": {"workflowId", "status", "message"}}`, without `pendingReason`. Once it completes, it prints the completion as `data`; `--wait` waits for that. A failed workflow prints nothing on stdout: stderr gets `{"error": "<reason>", "message": "…"}` and the command exits with that reason's [exit code](/cli/flags-and-output#exit-codes) – `4` for `linkedinAccountSignedOut` and `languageNotSupported`, `1` for any other, such as `cancelledByUser` or `workingHoursWaitExpired`. See [workflow status](/cli/workflows#workflow-status). These are the API responses it reads:
:::

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 Linked API does not support yet. Supported languages are English, German, Spanish, French and Portuguese. If you need another one, please contact our support – we prioritize new languages based on user requests.
  - `cancelledByUser` – the workflow was cancelled before it finished: on the [platform](https://app.linkedapi.io/stats) or through the API (see [Cancelling workflows](#cancelling-workflows)), or because its account was frozen (including automatically after a seat reduction or a failed payment), deleted, had its proxy changed, or was opened for browser access with its workflows stopped.
  - `workingHoursWaitExpired` – the workflow was parked by the account's [working hours](/docs/working-hours) and was not started within 7 days.
  - `unexpectedError` – the workflow failed for a reason on our side. The team has been notified; retry it, and contact support if it fails again.

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

## 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 from your code:

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

```typescript tab=Node
// Call cancel() on the same method you used to start the workflow
const cancelled = await linkedapi.checkConnectionStatus.cancel(workflowId);
```

```python tab=Python
# Call cancel() on the same method you used to start the workflow
cancelled = linkedapi.check_connection_status.cancel(workflow_id)
```

```bash tab=CLI
# The CLI has no cancel command: send the HTTP request with curl
curl -X DELETE "https://api.linkedapi.io/workflows/$WORKFLOW_ID" \
  -H "linked-api-token: your-linked-api-token" \
  -H "identification-token: your-identification-token"
```

:::surface cli
The CLI has no cancel command: send the request with `curl`, as above, or cancel the workflow on the [platform](https://app.linkedapi.io/stats).
:::

:::surface http,cli
Upon successful cancellation, you will receive the following response:
:::

:::surface node,python
**Under the hood** – `cancel()` returns `true` (`True` in Python) when this response reports the workflow cancelled; an unsuccessful request throws `LinkedApiError`:
:::

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

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

**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.
