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
limit number 50 Number of records (up to 5000). When limit > 50, auto-pagination is applied
offset number 0 Skip N records. When offset > 0, limit ≤ 500 is recommended
select string — Field selection: ?select=id,subject,typeId,completed
sort string — Sorting via the short syntax: ?sort=-deadline, the minus means descending
order object — Sorting: ?order[deadline]=asc
filter object — Filtering by the fields from GET /v1/activities/fields.
Filtering syntax. Example: ?filter[ownerTypeId]=2&filter[ownerId]=741
include string — Related 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
data array Array of activities (fields — see Fields)
meta.total number Total number of records
meta.hasMore boolean More records available
meta.includeSkipped boolean true 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
responsible responsibleId — the responsible person responsible Employee card or null
author authorId — the author author Employee card or null
editor editorId — the last editor editor Employee card or null

The employee card is the same as in the GET /v1/users/:id response. The relation reads an employee, so the key needs 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
400 INVALID_INCLUDE include contains a name outside the set responsible, author, editor. The response lists the available names
400 INVALID_INCLUDE include is not a comma-separated string of names (for example, include[a]=1). The response does not list the names
400 INCLUDE_LIMIT_EXCEEDED include contains more than three names, including duplicates
403 SCOPE_DENIED The API key lacks the crm scope
403 SCOPE_DENIED include requests a relation to an employee, and the key lacks the user scope. The response names the relation and the missing scope
401 TOKEN_MISSING The API key has no configured tokens
429 RATE_LIMITED Rate limit exceeded: 300 requests per minute per portal, all API keys of the portal share one limit. The exact value arrives in the x-ratelimit-limit header (the cap is divided across replicas). Retry after the delay in the Retry-After header

Full list of common API errors — 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