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

List activities

GET /v1/activities

Returns a list of CRM activities with support for filtering, sorting and auto-pagination. Filtering by ownerId + ownerTypeId returns the activities of a specific deal, lead or contact.

Parameters

Parameter Type Default Description
Parameterlimit Typenumber Default50 DescriptionNumber of records (up to 5000). When limit > 50, auto-pagination is applied
Parameteroffset Typenumber Default0 DescriptionSkip N records. When offset > 0, limit ≤ 500 is recommended
Parameterselect Typestring Default— DescriptionField selection: ?select=id,subject,typeId,completed
Parametersort Typestring Default— DescriptionSorting via the short syntax: ?sort=-deadline, the minus means descending
Parameterorder Typeobject Default— DescriptionSorting: ?order[deadline]=asc
Parameterfilter Typeobject Default— DescriptionFiltering by the fields from GET /v1/activities/fields.
Filtering syntax. Example: ?filter[ownerTypeId]=2&filter[ownerId]=741
Parameterinclude Typestring Default— DescriptionRelated employees, comma-separated: responsible, author, editor. See the "Related data" section below

Examples

curl — personal key

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/activities?filter[ownerTypeId]=2&filter[ownerId]=741&limit=10&select=id,subject,typeId,completed" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl -g "https://vibecode.bitrix24.com/v1/activities?filter[ownerTypeId]=2&filter[ownerId]=741&limit=10&select=id,subject,typeId,completed" \
  -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/activities?filter[ownerTypeId]=2&filter[ownerId]=741&limit=10&select=id,subject,typeId,completed', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Found ${meta.total} activities`)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/activities?filter[ownerTypeId]=2&filter[ownerId]=741&limit=10&select=id,subject,typeId,completed', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Response fields

Field Type Description
Fielddata Typearray DescriptionArray of activities (fields — see Fields)
Fieldmeta.total Typenumber DescriptionTotal number of records
Fieldmeta.hasMore Typeboolean DescriptionMore records available
Fieldmeta.includeSkipped Typeboolean Descriptiontrue if the response holds more than 200 records and the relations from include are not loaded. Reduce limit. With 200 records or fewer, the field is absent

To get the employees related to the activities together with the list, pass the include parameter in the GET request:

GET /v1/activities?filter[ownerTypeId]=3&filter[ownerId]=409&include=responsible,author

Available includes — up to three names per request:

Name Source field Key in _included Result
Nameresponsible Source fieldresponsibleId — the responsible person Key in _includedresponsible ResultEmployee card or null
Nameauthor Source fieldauthorId — the author Key in _includedauthor ResultEmployee card or null
Nameeditor Source fieldeditorId — the last editor Key in _includededitor ResultEmployee card or null

The employee card is the same as in the GET /v1/users/:id response. Loading employee details requires the user scope in addition to crm. The result is in the _included field of every data element:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 1111,
      "subject": "Sales proposal",
      "ownerTypeId": 3,
      "ownerId": 409,
      "responsibleId": 29,
      "authorId": 1,
      "_included": {
        "responsible": { "id": 29, "name": "Emma", "lastName": "Wilson", "email": "emma.wilson@example.com", "active": false },
        "author": { "id": 1, "name": "John", "lastName": "Brown", "email": "john.brown@example.com", "active": true }
      }
    }
  ],
  "meta": { "total": 1, "hasMore": false }
}

The main fields of the activity and the employee are shown. For the full list of card fields, see Employee fields. If the response holds more than 200 records, relations are not loaded and meta carries includeSkipped: true — reduce limit.

The responsibleId, authorId, and editorId fields do not have to be listed in select: the card arrives even when they are not selected, and the fields themselves are not added to the response.

Response example

JSON 
{
  "success": true,
  "data": [
    {
      "id": 3894,
      "typeId": 1,
      "ownerTypeId": 2,
      "ownerId": 741,
      "subject": "Project meeting",
      "responsibleId": 1,
      "priority": 2,
      "direction": 2,
      "completed": false,
      "deadline": "2026-04-16T11:00:00+00:00",
      "createdAt": "2026-04-15T14:30:00+00:00",
      "updatedAt": "2026-04-15T14:30:00+00:00"
    }
  ],
  "meta": {
    "total": 84,
    "hasMore": true
  }
}

Error response example

403 — no scope:

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

Errors

HTTP Code Description
HTTP400 CodeINVALID_INCLUDE Descriptioninclude contains a name outside the set responsible, author, editor. The response lists the available names
HTTP400 CodeINVALID_INCLUDE Descriptioninclude is not a comma-separated string of names (for example, include[a]=1). The response does not list the names
HTTP400 CodeINCLUDE_LIMIT_EXCEEDED Descriptioninclude contains more than three names, including duplicates
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the crm scope
HTTP403 CodeSCOPE_DENIED Descriptioninclude requests a relation to an employee, and the key lacks the user scope. The response names the relation and the missing scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of common API errors, see Errors.

Known specifics

Auto-pagination: with limit > 50, Vibecode automatically requests several pages.

Filter by entity: to get the activities of a specific deal, use filter[ownerTypeId]=2&filter[ownerId]=741. The ownerTypeId values: 1 — lead, 2 — deal, 3 — contact, 4 — company.

Fields for grouping and aggregation: typeId, ownerTypeId, responsibleId, authorId, editorId, completed, status, direction, providerId, providerTypeId. Used in POST /v1/activities/aggregate (see Aggregate activities).

Activities without a deadline: for activities with no deadline set, the field is returned with the sentinel value 9999-12-30T21:00:00.000Z — not a real date. A less-than date filter, for example filter[<deadline]=2027-01-01T00:00:00, does not match such activities, so they do not appear in a list of overdue activities.

See also