Executing workflows

For details on how to build workflows, visit the 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

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

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

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

console.log(workflow.workflowId);

from linkedapi import CheckConnectionStatusParams

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

print(workflow.workflow_id)

linkedin workflow run <<'JSON'
{
  "actionType": "st.checkConnectionStatus",
  "personUrl": "https://www.linkedin.com/in/person1"
}
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 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.

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

• error – either a common error or one of the following specific errors:
  • invalidWorkflow – workflow configuration is not valid due to violated action constraints or invalid action parameters, 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.
  • plusPlanRequired – the workflow contains Sales Navigator actions (nv.*), which need a Plus seat and a Sales Navigator subscription on the LinkedIn account.
  • linkedinAccountSignedOut – the LinkedIn account has been signed out in our cloud browser. Reconnect it on the platform.
  • outsideWorkingHours – the account is outside its configured 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 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:

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

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

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

# 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)

# Check the current status
linkedin workflow status abc123

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

1. Workflow is pending (queued for execution):

{
  "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. In that case pendingReason is outsideWorkingHours and the workflow will not move until the window reopens, which can be the next working day:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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 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.

In case of an unsuccessful request, you'll receive one of the 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. Simply click the three dots menu next to the workflow and select "Cancel".

Alternatively, you can cancel a workflow from your code:

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

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

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

# 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"

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

In case of an unsuccessful request, you'll receive one of the 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.