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

List recurring deals

GET /v1/recurring-deals

Returns deal recurrence settings with filtering, sorting and field selection. Use it to review schedules and their activity.

Parameters

Field Type Required Description
Fieldfilter Typeobject RequiredNo DescriptionFilter by fields from Recurring deal fields.
Filtering syntax. Example: ?filter[active]=false, or a JSON string
Fieldsort Typestring / object / string[] RequiredNo DescriptionSort fields. id sorts ascending, -id descending
Fieldorder Typeobject RequiredNo DescriptionAlternative to sort, for example {"id":"desc"}
Fieldselect Typestring / string[] RequiredNo DescriptionResponse fields. A comma-separated string or an array of names
Fieldlimit Typenumber RequiredNo DescriptionSelection size, default 50, maximum 5000
Fieldoffset Typenumber RequiredNo DescriptionOffset from the start of the selection
FieldwithTotal Typeboolean RequiredNo DescriptionRequests the total count. With false, meta.total is still returned

Pagination. The server reads multiple pages for limit > 50, up to 5000 records per request. Use offset and meta.hasMore to continue reading.

Examples

curl — personal key

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/recurring-deals?filter%5Bactive%5D=false&sort=-id&select=id,active&limit=2&withTotal=false" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -X GET "https://vibecode.bitrix24.com/v1/recurring-deals?filter%5Bactive%5D=false&sort=-id&select=id,active&limit=2&withTotal=false" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/recurring-deals?filter%5Bactive%5D=false&sort=-id&select=id,active&limit=2&withTotal=false', {
  method: 'GET',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const result = await response.json()
if (!result.success) throw new Error(result.error.message)
console.log(result.data)

JavaScript — OAuth application

javascript 
const response = await fetch('https://vibecode.bitrix24.com/v1/recurring-deals?filter%5Bactive%5D=false&sort=-id&select=id,active&limit=2&withTotal=false', {
  method: 'GET',
  headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN' },
})
const result = await response.json()
if (!result.success) throw new Error(result.error.message)
console.log(result.data)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionWhether the request succeeded
Fielddata Typeobject[] DescriptionRecurrence settings. See recurring deal fields
Fieldmeta.total Typenumber DescriptionTotal matching settings, when returned
Fieldmeta.hasMore Typeboolean DescriptionWhether more records are available
Fieldmeta.warnings Typeobject[] DescriptionWarnings, when returned. Unknown select fields can be ignored in a successful request

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 17,
      "active": false
    },
    {
      "id": 9,
      "active": false
    }
  ],
  "meta": {
    "total": 4,
    "hasMore": true
  }
}

Error response example

400 — unknown filter field:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'unknownField' for entity 'recurring-deals'. Available: id, dealId, basedId, active, nextExecution, lastExecution, counterRepeat, startDate, categoryId, isLimit, limitRepeat, limitDate"
  }
}

Errors

HTTP Code Description
HTTP400 CodeUNKNOWN_FILTER_FIELD DescriptionThe filter references an unknown field. See the error message and field definitions
HTTP400 CodeINVALID_FILTER_FIELD DescriptionA field name starts with the unsupported prefix @ or !@
HTTP400 CodeINVALID_FILTER_OPERATOR DescriptionAn unknown operator, an empty condition object, or a logical condition using $or or $and
HTTP400 CodeINVALID_DUPLICATE_FILTER_FIELD DescriptionTwo conditions map to the same filter condition. Supply only one
HTTP400 CodeINVALID_SORT_FIELD DescriptionSorting uses a forbidden name: __proto__, constructor or prototype
HTTP400 CodeUNKNOWN_SORT_FIELD DescriptionSorting references an unknown field
HTTP400 CodeINVALID_SORT_DIRECTION DescriptionA sort direction is not one of the strings asc, desc, ASC, DESC or the numbers 1, -1
HTTP400 CodeINVALID_FILTER Descriptionfilter is not an object or a JSON string containing an object, or two filter formats are mixed
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionNo Bitrix24 access tokens are configured
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the crm scope
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access, including a missing required scope
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the operation or a plan restriction applies. See error.message
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 did not respond in time. Retry after the interval in Retry-After
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionA connection to Bitrix24 could not be established
HTTP429 CodeRATE_LIMITED DescriptionThe request rate limit was exceeded. The effective limit is in the x-ratelimit-limit header. Retry after the interval in the Retry-After header

For the full list of common API errors, see Error codes.

Known specifics

The response can include settings with active: false. To retrieve active schedules only, filter by active: true.

See also