> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Leave Balances

> Call this API to query leave balances by leave type and employee ID with pagination. Each call returns up to 50 records.

Call this API to query leave balances by organization or employee with pagination. Each call returns up to 50 records.

## Request

| **Basic Information** | |
| - | - |
| HTTP URL | [https://api.dingtalk.io/topapi/attendance/vacation/quota/list](https://api.dingtalk.io/topapi/attendance/vacation/quota/list) |
| HTTP Method | POST |
| Supported app types | appType-Internal app　appType-Third-party enterprise app |
| Required permissions | permission-qyapi\_holiday\_readonly-DingTalk leave read permission |

### Query Parameters

| Name | Type | Required | Example | Description |
| - | - | - | - | - |
| access\_token | String | Yes | bE74xxxx | The app credential used to call this API.   - Internal app: Obtain it by calling the [Get the access\_token of an Internal App](https://help.dingtalk.io/open/development/obtain-orgapp-token) API. - Third-party enterprise app: Obtain it by calling the API for getting a third-party enterprise's access\_token. |

### Request Body

| Name | Type | Required | Example | Description |
| - | - | - | - | - |
| leave\_code | String | Yes | f84a2xxxx | The unique identifier of the leave type. Call the [Query the List of Leave Rules](https://help.dingtalk.io/open/development/holiday-type-query.md) API to obtain the leave\_code value. |
| op\_userid | String | Yes | user01 | The user ID of an admin in your organization who has app permissions for **OA Approval**. |
| userids | String | Yes | user02,user03 | The list of employee IDs to query. |
| offset | Number | Yes | 0 | The pagination offset. Must be a non-negative integer starting from 0. |
| size | Number | Yes | 10 | The page size. Maximum value: 50. |

### Request Example

```curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://api.dingtalk.io/topapi/attendance/vacation/quota/list" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=48acxxxx0dbdbee' \
-d 'leave_code=f84a2829-d245-4312-9ff2-0653e5b3abb2' \
-d 'offset=0' \
-d 'op_userid=zhangsan' \
-d 'size=10' \
-d 'userids=zhangsan%2Clisi'
```

Java

```java theme={"theme":{"light":"github-light","dark":"github-dark"}}
DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/vacation/quota/list");
OapiAttendanceVacationQuotaListRequest req = new OapiAttendanceVacationQuotaListRequest();
req.setLeaveCode("f84a2xxxx");
req.setOpUserid("user01");
req.setUserids("user02,user03");
req.setOffset(0L);
req.setSize(10L);
OapiAttendanceVacationQuotaListResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
```

Python

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import dingtalk.api

req=dingtalk.api.OapiAttendanceVacationQuotaListRequest("https://api.dingtalk.io/topapi/attendance/vacation/quota/list")

req.leave_code="f84a2829-d245-4312-9ff2-0653e5b3abb2"
req.op_userid="zhangsan"
req.userids="zhangsan,lisi"
req.offset=0
req.size=10
try:
  resp= req.getResponse(access_token)
  print(resp)
except Exception,e:
  print(e)
```

PHP

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');

$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiAttendanceVacationQuotaListRequest;
$req->setLeaveCode("f84a2829-d245-4312-9ff2-0653e5b3abb2");
$req->setOpUserid("zhangsan");
$req->setUserids("zhangsan,lisi");
$req->setOffset("0");
$req->setSize("10");
$resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/attendance/vacation/quota/list");
```

C#

```csharp theme={"theme":{"light":"github-light","dark":"github-dark"}}
IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/attendance/vacation/quota/list");
OapiAttendanceVacationQuotaListRequest req = new OapiAttendanceVacationQuotaListRequest();
req.LeaveCode = "f84a2829-d245-4312-9ff2-0653e5b3abb2";
req.OpUserid = "zhangsan";
req.Userids = "zhangsan,lisi";
req.Offset = 0L;
req.Size = 10L;
OapiAttendanceVacationQuotaListResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);
```

## Response

### Response Body

| Name | Type | Example | Description |
| - | - | - | - |
| result | OapiLeaveQuotaUserListVo | | The returned result. |
| has\_more | Boolean | false | Indicates whether more records exist.   - **true**: More records exist. - **false**: No more records exist. |
| leave\_quotas | Leavequotas\[] | | The list of leave balances. |
| userid | String | user01 | The user ID of the employee. |
| leave\_code | String | f84a2xxxx | The unique identifier of the leave type. |
| quota\_cycle | String | 2019 | The cycle that the quota applies to. |
| quota\_id | String | f8abb2xxxx | The unique identifier of the quota. |
| start\_time | Number | 1653851001000 | The start time of the leave validity period, as a timestamp in milliseconds. |
| end\_time | Number | 1753851001000 | The end time of the quota validity period, as a timestamp in milliseconds. |
| quota\_num\_per\_hour | Number | 1000 | The total quota, calculated in hours.  **Note**  When the leave type is calculated in hours, this value is not empty and is expressed in hundredths of an hour.  For example, 1000 = 10 hours. |
| quota\_num\_per\_day | Number | 1000 | The total quota, calculated in days.  **Note**  When the leave type is calculated in days, this value is not empty and is expressed in hundredths of a day.  For example, 1000 = 10 days. |
| used\_num\_per\_day | Number | 100 | The used quota, calculated in days.  **Note**  When the leave type is calculated in days, this value is not empty and is expressed in hundredths of a day.  For example, 100 = 1 day. |
| used\_num\_per\_hour | Number | 1000 | The used quota, calculated in hours.  **Note**  When the leave type is calculated in hours, this value is not empty and is expressed in hundredths of an hour.  For example, 1000 = 10 hours. |
| errcode | Number | 0 | The return code. |
| errmsg | String | ok | The description of the return code. |
| success | Boolean | true | Indicates whether the call succeeded.   - **true**: Yes - **false**: No |

### Response Body Example

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "errcode": 0,
  "result": {
    "has_more": false,
    "leave_quotas": [
      {
        "end_time": 1753851001000,
        "leave_code": "f84a2xxxx",
        "quota_cycle": "2019",
        "quota_id": "f8abb2xxxx",
        "quota_num_per_day": 1000,
        "start_time": 1653851001000,
        "used_num_per_day": 100,
        "quota_num_per_hour": 1000,
        "userid": "user01",
        "used_num_per_hour": 1000
      }
    ]
  },
  "success": true,
  "request_id": "exz4w88xfo7n"
}
```

### Error Codes

If a call to this API fails, find a solution based on the error message in the [Global Error Codes](https://help.dingtalk.io/open/development/server-api-error-codes-1.md) document.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.