#List of running workflows

GET /v1/workflows

Returns running workflow instances on the portal, 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.tech/v1/workflows \
  -H "X-Api-Key: YOUR_API_KEY"

#curl — OAuth application

Terminal 
curl https://vibecode.bitrix24.tech/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.tech/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.tech/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[].MODIFIED string Last modification date (ISO 8601)
data[].OWNED_UNTIL string | null Lock date for executing the current step; null if not locked
data[].MODULE_ID string Entity module (for example crm)
data[].ENTITY string Document class (for example CCrmDocumentDeal)
data[].DOCUMENT_ID string Document identifier in TYPENAME_ID format (for example DEAL_5141)
data[].STARTED string Start date (ISO 8601)
data[].STARTED_BY string ID of the user who started the process ("0" — system start)
data[].TEMPLATE_ID string Workflow template ID
meta.total number Total number of instances found

#Response example

JSON 
{
  "success": true,
  "data": [
    {
      "ID": "69f0c2d5ade389.22457798",
      "MODIFIED": "2026-04-28T17:23:17+03:00",
      "OWNED_UNTIL": null,
      "MODULE_ID": "crm",
      "ENTITY": "CCrmDocumentDeal",
      "DOCUMENT_ID": "DEAL_5141",
      "STARTED": "2026-04-28T17:23:17+03:00",
      "STARTED_BY": "0",
      "TEMPLATE_ID": "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

  • DOCUMENT_ID 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