For AI agents: markdown of this page — /docs-content-en/automation/workflows/list.md documentation index — /llms.txt

List of running workflows

GET /v1/workflows

Returns running workflow instances on your Bitrix24 account, sorted by modification date (newest first).

Parameters

Parameter Type Description
templateId number Filter by workflow template ID
startedBy number Filter by ID of the user who started the process
offset number Offset for pagination. Defaults to 0

Examples

curl — personal key

Terminal 
curl https://vibecode.bitrix24.com/v1/workflows \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.com/v1/workflows \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workflows', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data, meta } = await res.json()
console.log(`Processes: ${meta.total}`, data)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workflows', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Response fields

Field Type Description
success boolean Always true on success
data array Array of workflow instances
data[].id string Unique instance identifier
data[].modifiedAt string Last modification date (ISO 8601)
data[].ownedUntil string | null Lock date for executing the current step. null if not locked
data[].moduleId string Entity module (for example crm)
data[].entity string Document class (for example CCrmDocumentDeal)
data[].documentId string Document identifier in TYPENAME_ID format (for example DEAL_5141)
data[].startedAt string Start date (ISO 8601)
data[].startedBy string ID of the user who started the process ("0" — system start)
data[].templateId string Workflow template ID
meta.total number Total number of instances found

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": "69f0c2d5ade389.22457798",
      "modifiedAt": "2026-04-28T17:23:17+00:00",
      "ownedUntil": null,
      "moduleId": "crm",
      "entity": "CCrmDocumentDeal",
      "documentId": "DEAL_5141",
      "startedAt": "2026-04-28T17:23:17+00:00",
      "startedBy": "0",
      "templateId": "713"
    }
  ],
  "meta": {
    "total": 1
  }
}

Error response example

403 — no bizproc scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'bizproc' scope"
  }
}

Errors

HTTP Code Description
401 MISSING_API_KEY The X-Api-Key header was not provided
401 INVALID_API_KEY Invalid or expired API key
401 TOKEN_MISSING The key has no connected Bitrix24 tokens
401 TOKEN_EXPIRED The OAuth user session has expired — re-authorize via /v1/oauth/authorize
403 SCOPE_DENIED The key is missing the bizproc scope
403 BITRIX_ACCESS_DENIED Bitrix24 denied access
429 RATE_LIMITED Request limit exceeded. Retry in 1–2 seconds
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable

Full list of common API errors — Errors.

Known specifics

  • documentId is a string, not an array. The field is returned as a string in "TYPENAME_ID" format (for example "DEAL_5141"), not as an array. When starting a process via POST /v1/workflows/start, the document identifier is passed to Bitrix24 as an array, but in this endpoint's response it is normalized to a string.

See also