bizproc-workflow-instances.md

Get a list of running workflows bizproc.workflow.instances

{% note tip "" %}

If you are developing integrations for Bitrix24 using AI tools (Codex, Claude Code, Cursor), connect to the MCP server so that the assistant can utilize the official REST documentation.

{% endnote %}

Scope: bizproc

Who can execute the method: administrator

This method retrieves a list of running workflows.

{% note info "bizproc.workflow.instance.list" %}

There is an old method bizproc.workflow.instance.list — an alias for the method bizproc.workflow.instances. It accepts the same parameters and returns the same results.

Support for bizproc.workflow.instance.list is not guaranteed in the future, so we recommend using bizproc.workflow.instances.

{% endnote %}

Method Parameters

#| || Name type | Description || || SELECT array | An array containing the list of fields to select.

You can specify only the fields that are necessary.

Available fields:

• ID — identifier of the workflow
• MODIFIED — date of the last modification
• OWNED_UNTIL — time the workflow is locked. The process is considered stuck if the difference between the lock time and the current time is more than 5 minutes
• MODULE_ID — module identifier by document
• ENTITY — entity identifier by document
• DOCUMENT_ID — document identifier
• STARTED — date the workflow was started
• STARTED_BY — who started the workflow
• TEMPLATE_ID — identifier of the workflow template

Default value: ['ID', 'MODIFIED', 'OWNED_UNTIL'] || || FILTER object | An object for filtering the list of running workflows in the format {"field_1": "value_1", ... "field_N": "value_N"}.

The list of filterable fields is the same as for the SELECT parameter.

You can specify the type of filtering before the name of the filtered field:

• = — equal
• ! or != — not equal
• < — less than
• <= — less than or equal to
• > — greater than
• >= — greater than or equal to

Without a prefix, the filter compares the value for equality. The field name can be passed in any case || || ORDER object | An object for sorting the list of running workflows in the format {"field_1": "value_1", ... "field_N": "value_N"}.

The list of fields for sorting is the same as for the SELECT parameter.

The sorting direction can take the following values:

• asc — ascending
• desc — descending

Default value: {'MODIFIED': 'desc'} || || start integer | This parameter is used for managing pagination.

The page size of results is always static — 50 records.

To select the second page of results, you need to pass the value 50. To select the third page of results — the value 100, and so on.

The formula for calculating the value of the start parameter:

start = (N - 1) * 50, where N — the number of the desired page || |#

Code Examples

{% include Note on examples %}

{% list tabs %}

• cURL (Webhook)

  curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"select":["ID","MODIFIED","OWNED_UNTIL","MODULE_ID","ENTITY","DOCUMENT_ID","STARTED","STARTED_BY","TEMPLATE_ID"],"order":{"STARTED":"DESC"},"filter":{">STARTED_BY":0}}' \
  https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/bizproc.workflow.instances

• cURL (OAuth)

  curl -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"select":["ID","MODIFIED","OWNED_UNTIL","MODULE_ID","ENTITY","DOCUMENT_ID","STARTED","STARTED_BY","TEMPLATE_ID"],"order":{"STARTED":"DESC"},"filter":{">STARTED_BY":0},"auth":"**put_access_token_here**"}' \
  https://**put_your_bitrix24_address**/rest/bizproc.workflow.instances

• JS

  try
  {
  	const response = await $b24.callMethod(
  		'bizproc.workflow.instances',
  		{
  			select: [
  				'ID',
  				'MODIFIED',
  				'OWNED_UNTIL',
  				'MODULE_ID',
  				'ENTITY',
  				'DOCUMENT_ID',
  				'STARTED',
  				'STARTED_BY',
  				'TEMPLATE_ID'
  			],
  			order: {
  				STARTED: 'DESC'
  			},
  			filter: {
  				'>STARTED_BY': 0
  			}
  		}
  	);
  	
  	const result = response.getData().result;
  	console.log(result);
  }
  catch( error )
  {
  	alert("Error: " + error);
  }

• PHP

  try {
      $response = $b24Service
          ->core
          ->call(
              'bizproc.workflow.instances',
              [
                  'select' => [
                      'ID',
                      'MODIFIED',
                      'OWNED_UNTIL',
                      'MODULE_ID',
                      'ENTITY',
                      'DOCUMENT_ID',
                      'STARTED',
                      'STARTED_BY',
                      'TEMPLATE_ID'
                  ],
                  'order' => [
                      'STARTED' => 'DESC'
                  ],
                  'filter' => [
                      '>STARTED_BY' => 0
                  ]
              ]
          );
  
      $result = $response
          ->getResponseData()
          ->getResult();
  
      if ($result->error()) {
          echo 'Error: ' . $result->error();
      } else {
          echo 'Success: ' . print_r($result->data(), true);
      }
  
  } catch (Throwable $e) {
      error_log($e->getMessage());
      echo 'Error fetching workflow instances: ' . $e->getMessage();
  }

• BX24.js

  BX24.callMethod(
      'bizproc.workflow.instances',
      {
          select: [
              'ID',
              'MODIFIED',
              'OWNED_UNTIL',
              'MODULE_ID',
              'ENTITY',
              'DOCUMENT_ID',
              'STARTED',
              'STARTED_BY',
              'TEMPLATE_ID'
          ],
          order: {
              STARTED: 'DESC'
          },
          filter: {
              '>STARTED_BY': 0
          }
      },
      function(result)
      {
          if(result.error())
              alert("Error: " + result.error());
          else
              console.log(result.data());
      }
  );

• PHP CRest

  require_once('crest.php');
  
  $result = CRest::call(
      'bizproc.workflow.instances',
      [
          'select' => [
              'ID',
              'MODIFIED',
              'OWNED_UNTIL',
              'MODULE_ID',
              'ENTITY',
              'DOCUMENT_ID',
              'STARTED',
              'STARTED_BY',
              'TEMPLATE_ID'
          ],
          'order' => [
              'STARTED' => 'DESC'
          ],
          'filter' => [
              '>STARTED_BY' => 0
          ]
      ]
  );
  
  echo '<PRE>';
  print_r($result);
  echo '</PRE>';

• Go

  // client and ctx are already created — see the Go SDK section
  res, err := client.Core().Call(ctx, "bizproc.workflow.instances", b24.Params{
  	"SELECT": []string{"ID", "MODIFIED", "OWNED_UNTIL", "MODULE_ID", "ENTITY", "DOCUMENT_ID", "STARTED", "STARTED_BY", "TEMPLATE_ID"},
  	"ORDER": b24.Params{
  		"STARTED": "DESC",
  	},
  	"FILTER": b24.Params{
  		">STARTED_BY": 0,
  	},
  })
  if err != nil {
  	return fmt.Errorf("bizproc.workflow.instances: %w", err)
  }
  
  // The response arrives as json.RawMessage — unmarshal it
  // into a struct matching the response shape shown below on this page.
  fmt.Printf("%s\n", res.Result)

{% endlist %}

Response Handling

HTTP status: 200

{
    "result":[
        {
            "DOCUMENT_ID": "LEAD_1",
            "ENTITY": "CCrmDocumentLead",
            "ID": "66e412fdc9bd44.36306599",
            "STARTED": "2024-09-13T10:25:01+00:00",
            "MODULE_ID": "crm",
            "OWNED_UNTIL": null,
            "TEMPLATE_ID": "1",
            "STARTED_BY": "0"
        },
        {
            "DOCUMENT_ID":"DEAL_1633",
            "ENTITY":"CCrmDocumentDeal",
            "ID":"658c4d3d6a2906.51542462",
            "STARTED":"2023-12-27T19:13:49+02:00",
            "MODULE_ID":"crm",
            "OWNED_UNTIL":null,
            "TEMPLATE_ID":"212",
            "STARTED_BY":"57"
        }
    ],
    "total": 2,
    "time": {
        "start": 1726476060.581428,
        "finish": 1726476060.813776,
        "duration": 0.23234796524047852,
        "processing": 0.002630949020385742,
        "date_start": "2024-09-16T08:41:00+00:00",
        "date_finish": "2024-09-16T08:41:00+00:00",
        "operating_reset_at": 1726476660,
        "operating": 0
    }
}

Returned Data

#| || Name type | Description || || result object | The root element of the response.

Contains an array of objects with information about running workflows || || total integer | The total number of records found || || time time | Information about the execution time of the request || |#

Error Handling

HTTP status: 403

{
    "error": "ACCESS_DENIED",
    "error_description": "Access denied!"
}

{% include notitle error handling %}

Possible Error Codes

#| || Status |Code | Description | Value || || 403 | ACCESS_DENIED | Access denied! | Method was executed by a non-administrator || |#

{% include system errors %}

Continue Learning

• {#T}
• {#T}
• {#T}
• {#T}
• {#T}
• {#T}