## Subordinate work reports

`GET /v1/workday/work-reports/subordinates`

Returns the submitted work reports of the credential owner and of the employees whose time records the owner can read. Useful for a manager reviewing the team's reports.

Requires the `timeman` scope and the credential owner's Bitrix24 right to read the time records of subordinates or of all employees. With the right to read the time records of all employees, the reports of the whole company are returned. READONLY keys can read reports.

## Parameters

| Parameter | Type | Required | Default | Description |
|----------|-----|:-----:|-----------|----------|
| `userId` (query) | integer | no | — | Employee ID — return only this employee's reports. List: [`GET /v1/users`](/docs/entities/users/list) |
| `userIds` (query) | string | no | — | Comma-separated employee IDs, for example `103,105`. If `userId` is also passed, the reports of all listed employees are returned. List: [`GET /v1/users`](/docs/entities/users/list) |
| `activeOnly` (query) | boolean | no | — | Accepted but does not change the result: only submitted reports are returned |
| `dateFrom` (query) | string | no | — | Period start in ISO 8601 format with a time zone. Reports whose period overlaps the given one are returned; the boundaries are inclusive |
| `dateTo` (query) | string | no | — | Period end in the same format |
| `limit` (query) | integer | no | `5` | How many employees to return, from 1 to 50 |
| `offset` (query) | integer | no | `0` | How many employees to skip. Cannot be combined with `page` |
| `page` (query) | integer | no | `1` | Page number, with `limit` employees per page. Cannot be combined with `offset` |

## Examples

### curl — personal key

```bash
curl "https://vibecode.bitrix24.com/v1/workday/work-reports/subordinates?userIds=103,105" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth application

```bash
curl "https://vibecode.bitrix24.com/v1/workday/work-reports/subordinates?userIds=103,105" \
  -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/workday/work-reports/subordinates?userIds=103,105', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const { data, meta } = await res.json()
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/work-reports/subordinates?userIds=103,105', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data, meta } = await res.json()
```

## Response fields

| Field | Type | Description |
|------|-----|----------|
| `success` | boolean | `true` when the request succeeds |
| `data` | array | Employees with submitted reports. An employee without matching reports is not included. The credential owner comes first if they have matching reports |
| `data[].userId` | integer | Employee ID. List: [`GET /v1/users`](/docs/entities/users/list) |
| `data[].user` | object \| null | The employee |
| `data[].user.id` | integer | Employee ID, the same as `userId` |
| `data[].user.name` | string | Employee's first and last name |
| `data[].user.photo` | string \| null | Profile photo URL |
| `data[].reports` | array | The employee's submitted reports in descending `id` order. For the report structure, see [Report fields](/docs/workday/work-reports/fields) |
| `meta.offset` | integer | How many employees were skipped |
| `meta.limit` | integer | How many employees fit on a page |
| `meta.hasMore` | boolean | `true` if more employees follow this page |
| `meta.nextOffset` | integer \| null | The `offset` value for the next page, or `null` if there are no more pages |
| `meta.paginationUnit` | string | Always `users`: `limit` and `offset` count employees, not reports |

## Response example

The main report fields are shown. For the full list, see [Report fields](/docs/workday/work-reports/fields):

```json
{
  "success": true,
  "data": [
    {
      "userId": 103,
      "user": {
        "id": 103,
        "name": "Anna Smith",
        "photo": null
      },
      "reports": [
        {
          "id": 79,
          "userId": 103,
          "active": true,
          "reportType": "week",
          "reportDate": "2023-03-02T10:39:37.000Z",
          "dateFrom": "2023-01-15T21:00:00.000Z",
          "dateTo": "2023-01-21T21:00:00.000Z",
          "report": "Hi :)",
          "type": "REPORT",
          "mark": "G",
          "approve": "Y"
        }
      ]
    },
    {
      "userId": 105,
      "user": {
        "id": 105,
        "name": "John Brown",
        "photo": null
      },
      "reports": [
        {
          "id": 115,
          "userId": 105,
          "active": true,
          "reportType": "week",
          "reportDate": "2024-02-14T11:34:24.000Z",
          "dateFrom": "2024-02-04T21:00:00.000Z",
          "dateTo": "2024-02-10T21:00:00.000Z",
          "report": "",
          "type": "REPORT",
          "mark": "X",
          "approve": "N"
        },
        {
          "id": 111,
          "userId": 105,
          "active": true,
          "reportType": "week",
          "reportDate": "2024-01-26T14:20:50.000Z",
          "dateFrom": "2024-01-21T21:00:00.000Z",
          "dateTo": "2024-01-27T21:00:00.000Z",
          "report": "",
          "type": "REPORT",
          "mark": "X",
          "approve": "N"
        }
      ]
    }
  ],
  "meta": {
    "offset": 0,
    "limit": 5,
    "hasMore": false,
    "nextOffset": null,
    "paginationUnit": "users"
  }
}
```

## Error response example

400 — `limit` is greater than 50:

```json
{
  "success": false,
  "error": {
    "code": "WORKDAY_REPORT_LIMIT_EXCEEDED",
    "message": "Report list limit must be between 1 and 50"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `WORKDAY_REPORT_LIMIT_EXCEEDED` | `limit` is greater than 50 |
| 400 | `INVALID_PARAMS` | `userId`, `limit`, or `page` is not a positive integer; `userIds` is not a comma-separated list of positive integers; `offset` is not a non-negative integer; `offset` and `page` were passed together; `activeOnly` is not `true`, `false`, `1`, or `0`; a date has no time zone, does not exist, or is not later than `1970-01-01T00:00:00Z`; an unknown parameter is passed, such as `order` or `select`; a parameter is passed twice |
| 403 | `BITRIX_ACCESS_DENIED` | The credential owner lacks the right to read the time records of subordinates or of all employees |
| 409 | `TIMEMAN_MODULE_NOT_ENABLED` | Time Management is not available on this portal |
| 422 | `BITRIX_ERROR` | Bitrix24 refused the operation |
| 502 | `BITRIX_UNAVAILABLE` | Bitrix24 is unavailable or returned a response of an unexpected shape |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |
| 401 | `TOKEN_MISSING` | An app key was sent without a session token in `Authorization: Bearer` |
| 401 | `INVALID_SESSION` | The session token is invalid or has expired |
| 403 | `SCOPE_DENIED` | The key lacks the `timeman` scope |
| 429 | `RATE_LIMITED` | The report read limit (30 requests per minute per key–user pair) or the general request limit was exceeded. The effective report read limit is in the `x-ratelimit-limit` header; the cap is divided across replicas |

The full list of common API errors — [Errors](/docs/errors).

## See also

- [List work reports](/docs/workday/work-reports/list)
- [Report fields](/docs/workday/work-reports/fields)
- [Work reports](/docs/workday/work-reports)
- [Daily reports](/docs/workday/daily-reports)
- [Workday](/docs/workday)