Query the event view - DingTalk Help Center

Call this API to query the event list of a user within a given time range. You can retrieve information such as the event title, start date, start time, end date, and end time.

API call description

The difference between this API and the Query event list API lies in how recurring events are handled. This API expands all recurring events within the query range based on the recurrence rule, but does not actually generate the corresponding instances in the database. For example, if there is a daily recurring event starting on January 1, the current date is January 4, and the query range is from January 1 to January 10, this API returns all recurring events from January 1 to January 10, whereas the Query event list API does not return events after January 4.
You can determine whether an event is an instance of a recurring event by checking whether the seriesMasterId of the returned event object is empty.

Request

Basic information

Field	Value
HTTP URL	`https://api.dingtalk.io/v1.0/calendar/users/{userId}/calendars/{calendarId}/eventsview`
HTTP Method	GET
Supported app types	appType-Internal app　appType-Third-party enterprise app　appType-Third-party personal app
Required permissions	permission-Calendar.Event.Read-Read permission for events in the Calendar app

Request headers

Name	Type	Required	Description
x-acs-dingtalk-access-token	String	Yes	The access credential for calling this API. Obtain it as follows: - For an internal app, call the Obtain the access token of an internal app API. - For a third-party enterprise app, call the Obtain the access token of an enterprise that authorizes a third-party app API. - For a third-party personal app, call the Obtain user token API.

Path parameters

Name	Type	Required	Description
userId	String	Yes	The unionId of the user to query. - For internal apps and third-party enterprise apps, call the Query user details API to obtain the `unionid` parameter value. - For third-party personal apps, call the Obtain a user’s profile from Contacts API to obtain the `unionId` parameter value.
calendarId	String	Yes	The calendar ID to which the event belongs. Call the Query calendars API to query events for the current user. Use the keyword primary to refer to the primary calendar of the current user.

Query parameters

Name	Type	Required	Description
timeMin	String	No	Query events whose end time is >= TimeMin. The format is the ISO-8601 date-time format.
timeMax	String	No	Query events whose start time is `< timeMax`. The format is the ISO-8601 date-time format.
maxResults	Integer	No	The maximum number of records to return. The maximum value is 100, and the default value is 100.
maxAttendees	Integer	No	The number of attendees returned for each event. The default value is 100, and the maximum value is 100. If the number of attendees exceeds 100 and you need to retrieve all attendees, use the Get event attendees API.
nextToken	String	No	The pagination cursor. If a single query cannot return all results, a pagination token is returned. Pass this token in the next query to retrieve subsequent data, until the pagination token is null, indicating that all data has been queried.

Request example

HTTP

GET /v1.0/calendar/users/iiiP35sJadxxx/calendars/primary/eventsview?timeMin=2022-11-27T00:00:00+08:00&timeMax=2022-11-28T00:00:00+08:00&maxResults=100&maxAttendees=100&nextToken=cnNTbW1xxx HTTP/1.1
Host:api.dingtalk.io
x-acs-dingtalk-access-token:dd43888xxx
Content-Type:application/json

Java

// This file is auto-generated, don't edit it. Thanks.
package com.aliyun.sample;

import com.aliyun.tea.*;

public class Sample {

    /**
     * <b>description</b> :
     * <p>Initialize the account client using a token</p>
     * @return Client
     * 
     * @throws Exception
     */
    public static com.aliyun.dingtalkcalendar_1_0.Client createClient() throws Exception {
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config();
        config.protocol = "https";
        config.regionId = "central";
        return new com.aliyun.dingtalkcalendar_1_0.Client(config);
    }

    public static void main(String[] args_) throws Exception {
        java.util.List<String> args = java.util.Arrays.asList(args_);
        com.aliyun.dingtalkcalendar_1_0.Client client = Sample.createClient();
        com.aliyun.dingtalkcalendar_1_0.models.ListEventsViewHeaders listEventsViewHeaders = new com.aliyun.dingtalkcalendar_1_0.models.ListEventsViewHeaders();
        listEventsViewHeaders.xAcsDingtalkAccessToken = "<your access token>";
        com.aliyun.dingtalkcalendar_1_0.models.ListEventsViewRequest listEventsViewRequest = new com.aliyun.dingtalkcalendar_1_0.models.ListEventsViewRequest()
                .setTimeMin("2022-11-27T00:00:00+08:00")
                .setTimeMax("2022-11-28T00:00:00+08:00")
                .setMaxResults(100)
                .setMaxAttendees(100)
                .setNextToken("cnNTbW1xxx");
        try {
            client.listEventsViewWithOptions("iiiP35sJadxxx", "primary", listEventsViewRequest, listEventsViewHeaders, new com.aliyun.teautil.models.RuntimeOptions());
        } catch (TeaException err) {
            if (!com.aliyun.teautil.Common.empty(err.code) && !com.aliyun.teautil.Common.empty(err.message)) {
                // err contains code and message properties, which help with debugging
            }

        } catch (Exception _err) {
            TeaException err = new TeaException(_err.getMessage(), _err);
            if (!com.aliyun.teautil.Common.empty(err.code) && !com.aliyun.teautil.Common.empty(err.message)) {
                // err contains code and message properties, which help with debugging
            }

        }        
    }
}

Python

# -*- coding: utf-8 -*-
# This file is auto-generated, don't edit it. Thanks.
import os
import sys

from typing import List

from alibabacloud_dingtalk.calendar_1_0.client import Client as dingtalkcalendar_1_0Client
from alibabacloud_tea_openapi import models as open_api_models
from alibabacloud_dingtalk.calendar_1_0 import models as dingtalkcalendar__1__0_models
from alibabacloud_tea_util import models as util_models
from alibabacloud_tea_util.client import Client as UtilClient

class Sample:
    def __init__(self):
        pass

    @staticmethod
    def create_client() -> dingtalkcalendar_1_0Client:
        """
        Initialize the account client using a token
        @return: Client
        @throws Exception
        """
        config = open_api_models.Config()
        config.protocol = 'https'
        config.region_id = 'central'
        return dingtalkcalendar_1_0Client(config)

    @staticmethod
    def main(
        args: List[str],
    ) -> None:
        client = Sample.create_client()
        list_events_view_headers = dingtalkcalendar__1__0_models.ListEventsViewHeaders()
        list_events_view_headers.x_acs_dingtalk_access_token = '<your access token>'
        list_events_view_request = dingtalkcalendar__1__0_models.ListEventsViewRequest(
            time_min='2022-11-27T00:00:00+08:00',
            time_max='2022-11-28T00:00:00+08:00',
            max_results=100,
            max_attendees=100,
            next_token='cnNTbW1xxx'
        )
        try:
            client.list_events_view_with_options('iiiP35sJadxxx', 'primary', list_events_view_request, list_events_view_headers, util_models.RuntimeOptions())
        except Exception as err:
            if not UtilClient.empty(err.code) and not UtilClient.empty(err.message):
                # err contains code and message properties, which help with debugging
                pass

    @staticmethod
    async def main_async(
        args: List[str],
    ) -> None:
        client = Sample.create_client()
        list_events_view_headers = dingtalkcalendar__1__0_models.ListEventsViewHeaders()
        list_events_view_headers.x_acs_dingtalk_access_token = '<your access token>'
        list_events_view_request = dingtalkcalendar__1__0_models.ListEventsViewRequest(
            time_min='2022-11-27T00:00:00+08:00',
            time_max='2022-11-28T00:00:00+08:00',
            max_results=100,
            max_attendees=100,
            next_token='cnNTbW1xxx'
        )
        try:
            await client.list_events_view_with_options_async('iiiP35sJadxxx', 'primary', list_events_view_request, list_events_view_headers, util_models.RuntimeOptions())
        except Exception as err:
            if not UtilClient.empty(err.code) and not UtilClient.empty(err.message):
                # err contains code and message properties, which help with debugging
                pass

if __name__ == '__main__':
    Sample.main(sys.argv[1:])

PHP

<?php

// This file is auto-generated, don't edit it. Thanks.
namespace AlibabaCloud\SDK\Sample;

use AlibabaCloud\SDK\Dingtalk\Vcalendar_1_0\Dingtalk;
use \Exception;
use AlibabaCloud\Tea\Exception\TeaError;
use AlibabaCloud\Tea\Utils\Utils;

use Darabonba\OpenApi\Models\Config;
use AlibabaCloud\SDK\Dingtalk\Vcalendar_1_0\Models\ListEventsViewHeaders;
use AlibabaCloud\SDK\Dingtalk\Vcalendar_1_0\Models\ListEventsViewRequest;
use AlibabaCloud\Tea\Utils\Utils\RuntimeOptions;

class Sample {

    /**
     * Initialize the account client using a token
     * @return Dingtalk Client
     */
    public static function createClient(){
        $config = new Config([]);
        $config->protocol = "https";
        $config->regionId = "central";
        return new Dingtalk($config);
    }

    /**
     * @param string[] $args
     * @return void
     */
    public static function main($args){
        $client = self::createClient();
        $listEventsViewHeaders = new ListEventsViewHeaders([]);
        $listEventsViewHeaders->xAcsDingtalkAccessToken = "<your access token>";
        $listEventsViewRequest = new ListEventsViewRequest([
            "timeMin" => "2022-11-27T00:00:00+08:00",
            "timeMax" => "2022-11-28T00:00:00+08:00",
            "maxResults" => 100,
            "maxAttendees" => 100,
            "nextToken" => "cnNTbW1xxx"
        ]);
        try {
            $client->listEventsViewWithOptions("iiiP35sJadxxx", "primary", $listEventsViewRequest, $listEventsViewHeaders, new RuntimeOptions([]));
        }
        catch (Exception $err) {
            if (!($err instanceof TeaError)) {
                $err = new TeaError([], $err->getMessage(), $err->getCode(), $err);
            }
            if (!Utils::empty_($err->code) && !Utils::empty_($err->message)) {
                // err contains code and message properties, which help with debugging
            }
        }
    }
}
$path = __DIR__ . \DIRECTORY_SEPARATOR . '..' . \DIRECTORY_SEPARATOR . 'vendor' . \DIRECTORY_SEPARATOR . 'autoload.php';
if (file_exists($path)) {
    require_once $path;
}
Sample::main(array_slice($argv, 1));

// This file is auto-generated, don't edit it. Thanks.
package main

import (
  "encoding/json"
  "strings"
  "fmt"
  "os"
  util  "github.com/alibabacloud-go/tea-utils/v2/service"
  dingtalkcalendar_1_0  "github.com/alibabacloud-go/dingtalk/calendar_1_0"
  openapi  "github.com/alibabacloud-go/darabonba-openapi/v2/client"
  "github.com/alibabacloud-go/tea/tea"
)

// Description:
// 
// Initialize the account client using a token
// 
// @return Client
// 
// @throws Exception
func CreateClient () (_result *dingtalkcalendar_1_0.Client, _err error) {
  config := &openapi.Config{}
  config.Protocol = tea.String("https")
  config.RegionId = tea.String("central")
  _result = &dingtalkcalendar_1_0.Client{}
  _result, _err = dingtalkcalendar_1_0.NewClient(config)
  return _result, _err
}

func _main (args []*string) (_err error) {
  client, _err := CreateClient()
  if _err != nil {
    return _err
  }

  listEventsViewHeaders := &dingtalkcalendar_1_0.ListEventsViewHeaders{}
  listEventsViewHeaders.XAcsDingtalkAccessToken = tea.String("<your access token>")
  listEventsViewRequest := &dingtalkcalendar_1_0.ListEventsViewRequest{
    TimeMin: tea.String("2022-11-27T00:00:00+08:00"),
    TimeMax: tea.String("2022-11-28T00:00:00+08:00"),
    MaxResults: tea.Int32(100),
    MaxAttendees: tea.Int32(100),
    NextToken: tea.String("cnNTbW1xxx"),
  }
  tryErr := func()(_e error) {
    defer func() {
      if r := tea.Recover(recover()); r != nil {
        _e = r
      }
    }()
    _, _err = client.ListEventsViewWithOptions(tea.String("iiiP35sJadxxx"), tea.String("primary"), listEventsViewRequest, listEventsViewHeaders, &util.RuntimeOptions{})
    if _err != nil {
      return _err
    }

    return nil
  }()

  if tryErr != nil {
    var err = &tea.SDKError{}
    if _t, ok := tryErr.(*tea.SDKError); ok {
      err = _t
    } else {
      err.Message = tea.String(tryErr.Error())
    }
    if !tea.BoolValue(util.Empty(err.Code)) && !tea.BoolValue(util.Empty(err.Message)) {
      // err contains code and message properties, which help with debugging
    }

  }
  return _err
}

func main() {
  err := _main(tea.StringSlice(os.Args[1:]))
  if err != nil {
    panic(err)
  }
}

Node.js

'use strict';
// This file is auto-generated, don't edit it
const Util = require('@alicloud/tea-util');
const dingtalkcalendar_1_0 = require('@alicloud/dingtalk/calendar_1_0');
const OpenApi = require('@alicloud/openapi-client');
const Tea = require('@alicloud/tea-typescript');

class Client {

  /**
   * Initialize the account client using a token
   * @return Client
   * @throws Exception
   */
  static createClient() {
    let config = new OpenApi.Config({ });
    config.protocol = 'https';
    config.regionId = 'central';
    return new dingtalkcalendar_1_0.default(config);
  }

  static async main(args) {
    let client = Client.createClient();
    let listEventsViewHeaders = new dingtalkcalendar_1_0.ListEventsViewHeaders({ });
    listEventsViewHeaders.xAcsDingtalkAccessToken = '<your access token>';
    let listEventsViewRequest = new dingtalkcalendar_1_0.ListEventsViewRequest({
      timeMin: '2022-11-27T00:00:00+08:00',
      timeMax: '2022-11-28T00:00:00+08:00',
      maxResults: 100,
      maxAttendees: 100,
      nextToken: 'cnNTbW1xxx',
    });
    try {
      await client.listEventsViewWithOptions('iiiP35sJadxxx', 'primary', listEventsViewRequest, listEventsViewHeaders, new Util.RuntimeOptions({ }));
    } catch (err) {
      if (!Util.default.empty(err.code) && !Util.default.empty(err.message)) {
        // err contains code and message properties, which help with debugging
      }

    }    
  }

}

exports.Client = Client;
Client.main(process.argv.slice(2));

// This file is auto-generated, don't edit it. Thanks.

using System;
using System.Collections;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;

using Tea;
using Tea.Utils;

namespace AlibabaCloud.SDK.Sample
{
    public class Sample 
    {

        /// <term><b>Description:</b></term>
        /// <description>
        /// <para>Initialize the account client using a token</para>
        /// </description>
        /// 
        /// <returns>
        /// Client
        /// </returns>
        /// 
        /// <term><b>Exception:</b></term>
        /// Exception
        public static AlibabaCloud.SDK.Dingtalkcalendar_1_0.Client CreateClient()
        {
            AlibabaCloud.OpenApiClient.Models.Config config = new AlibabaCloud.OpenApiClient.Models.Config();
            config.Protocol = "https";
            config.RegionId = "central";
            return new AlibabaCloud.SDK.Dingtalkcalendar_1_0.Client(config);
        }

        public static void Main(string[] args)
        {
            AlibabaCloud.SDK.Dingtalkcalendar_1_0.Client client = CreateClient();
            AlibabaCloud.SDK.Dingtalkcalendar_1_0.Models.ListEventsViewHeaders listEventsViewHeaders = new AlibabaCloud.SDK.Dingtalkcalendar_1_0.Models.ListEventsViewHeaders();
            listEventsViewHeaders.XAcsDingtalkAccessToken = "<your access token>";
            AlibabaCloud.SDK.Dingtalkcalendar_1_0.Models.ListEventsViewRequest listEventsViewRequest = new AlibabaCloud.SDK.Dingtalkcalendar_1_0.Models.ListEventsViewRequest
            {
                TimeMin = "2022-11-27T00:00:00+08:00",
                TimeMax = "2022-11-28T00:00:00+08:00",
                MaxResults = 100,
                MaxAttendees = 100,
                NextToken = "cnNTbW1xxx",
            };
            try
            {
                client.ListEventsViewWithOptions("iiiP35sJadxxx", "primary", listEventsViewRequest, listEventsViewHeaders, new AlibabaCloud.TeaUtil.Models.RuntimeOptions());
            }
            catch (TeaException err)
            {
                if (!AlibabaCloud.TeaUtil.Common.Empty(err.Code) && !AlibabaCloud.TeaUtil.Common.Empty(err.Message))
                {
                    // err contains code and message properties, which help with debugging
                }
            }
            catch (Exception _err)
            {
                TeaException err = new TeaException(new Dictionary<string, object>
                {
                    { "message", _err.Message }
                });
                if (!AlibabaCloud.TeaUtil.Common.Empty(err.Code) && !AlibabaCloud.TeaUtil.Common.Empty(err.Message))
                {
                    // err contains code and message properties, which help with debugging
                }
            }
        }

    }
}

Response

Response body

Name	Type	Description
nextToken	String	The pagination token.
events	Array	The event list.
id	String	The event ID.
summary	String	The event title.
description	String	The event description.
start	Object	The event start date.
date	String	The event start date, in the format yyyy-MM-dd.
dateTime	String	The event start time, in the ISO-8601 date-time format.
timeZone	String	The time zone of the event start time, in `tz database name` format.
originStart	Object	The start time when the event was originally created in the recurrence series. This property is not returned for regular single events.
dateTime	String	The date and time information in ISO 8601 format, always in UTC. For example, `January 1, 2023 at midnight UTC is 2023-01-01T00:00:00Z`.
end	Object	The event end time.
date	String	The event end date, in the format yyyy-MM-dd.
dateTime	String	The event end time, in the ISO-8601 date-time format.
timeZone	String	The time zone of the event end time. It must be the same as the time zone of the start time, in `tz database name` format.
isAllDay	Boolean	Whether the event is an all-day event. - true: Yes - false: No
recurrence	Object	The event recurrence rule.
pattern	Object	The recurrence pattern.
type	String	The recurrence rule type. - daily: Repeats every interval days - weekly: Repeats on daysOfWeek every interval weeks - absoluteMonthly: Repeats on day dayOfMonth every interval months - relativeMonthly: Repeats on daysOfWeek of the index week every interval months - absoluteYearly: Repeats every interval years
dayOfMonth	Integer	When type equals absoluteMonthly, this specifies which day of the month.
daysOfWeek	String	Specifies the day of the week using lowercase English words. Separate multiple values with commas.
index	String	When type = relativeMonthly, this specifies which week of the month. - first: The first week - second: The second week - third: The third week - fourth: The fourth week - last: The last week
interval	Integer	The recurrence interval. The unit varies based on type. For example, when type equals daily, it represents an interval of N days; when type equals absoluteYearly, it represents an interval of N years.
firstDayOfWeek	String	The first day of the week. Valid values: sunday, monday, tuesday, wednesday, thursday, friday, saturday. The default value is “sunday”.
range	Object	The recurrence range.
type	String	The recurrence range type. - noEnd: Never ends - endDate: Recurs until the specified date - numbered: Ends after the specified number of occurrences
endDate	String	The recurrence end date.
numberOfOccurrences	Integer	The number of occurrences.
attendees	Array	The event attendees.
id	String	The user unionId.
displayName	String	The user name.
responseStatus	String	The response status.
self	Boolean	Whether this is the currently signed-in user. - true: Yes - false: No
isOptional	Boolean	Whether this is an optional attendee. - true: Yes - false: No
organizer	Object	The event organizer.
id	String	The user unionId.
displayName	String	The user name.
responseStatus	String	The response status.
self	Boolean	Whether this is the currently signed-in user. - true: Yes - false: No
location	Object	The event location.
displayName	String	The display name.
meetingRooms	Array of String	The meeting rooms.
seriesMasterId	String	The ID of the master event of the recurring event. Empty for non-recurring events.
createTime	String	The created time.
updateTime	String	The update time.
status	String	The event status.
extendedProperties	Object	The event extended properties.
sharedProperties	Object	The shared properties.
sourceOpenCid	String	When the event is initiated from a group chat, this field indicates the source group of the event.
belongCorpId	String	The organization ID of the organization the event belongs to.
privateProperties	Object	The private properties.
dingtalkDetailUrl	String	The detail URL.
onlineMeetingInfo	Object	The online meeting.
type	String	The online meeting type. Currently supported: - dingtalk: DingTalk Video Meeting
conferenceId	String	The meeting ID.
url	String	The URL for joining the meeting.
extraInfo	Map	Other extended information.
categories	Array	The event categories.
displayName	String	The event category name.
richTextDescription	Object	The rich text description.
text	String	The content of the rich text description.
meetingRooms	Array	The meeting rooms.
roomId	String	The roomId of the meeting room.
responseStatus	String	The response status of the meeting room. - accepted: Accepted - tentative: Pending approval - declined: Approval rejected
displayName	String	The meeting room name.

Response body example

HTTP/1.1 200 OK
Content-Type:application/json

{
  "nextToken" : "cnNTbWxxx",
  "events" : [ {
    "id" : "cnNTbxxx",
    "summary" : "test event",
    "description" : "something about this event",
    "start" : {
      "date" : "2020-01-01",
      "dateTime" : "2020-01-01T10:15:30+08:00",
      "timeZone" : "Asia/Shanghai"
    },
    "originStart" : {
      "dateTime" : "2023-01-01T00:00:00Z"
    },
    "end" : {
      "date" : "2020-01-01",
      "dateTime" : "2020-01-01T10:15:30+08:00",
      "timeZone" : "Asia/Shanghai"
    },
    "isAllDay" : false,
    "recurrence" : {
      "pattern" : {
        "type" : "daily",
        "dayOfMonth" : 14,
        "daysOfWeek" : "sunday",
        "index" : "first",
        "interval" : 1,
        "firstDayOfWeek" : "monday"
      },
      "range" : {
        "type" : "noEnd",
        "endDate" : "2020-01-01T10:15:30+08:00",
        "numberOfOccurrences" : 5
      }
    },
    "attendees" : [ {
      "id" : "iiiP35xxx",
      "displayName" : "tony",
      "responseStatus" : "accepted",
      "self" : false,
      "isOptional" : false
    } ],
    "organizer" : {
      "id" : "iiiP35xxx",
      "displayName" : "jack",
      "responseStatus" : "accepted",
      "self" : false
    },
    "location" : {
      "displayName" : "room 1-2-3",
      "meetingRooms" : [ "Meeting room" ]
    },
    "seriesMasterId" : "cnNTbxxx",
    "createTime" : "2020-01-01T10:15:30+08:00",
    "updateTime" : "2020-01-01T10:15:30+08:00",
    "status" : "confirmed",
    "extendedProperties" : {
      "sharedProperties" : {
        "sourceOpenCid" : "zxcvasdfa123===",
        "belongCorpId" : "dingd8*****1231"
      },
      "privateProperties" : {
        "dingtalkDetailUrl" : "https://example.com"
      }
    },
    "onlineMeetingInfo" : {
      "type" : "dingtalk",
      "conferenceId" : "5c4df2xxx",
      "url" : "dingtalk://dingtalkclient/page/xxx?confId=xxx&calendarId=xxx"
    },
    "categories" : [ {
      "displayName" : "Weekly meeting"
    } ],
    "richTextDescription" : {
      "text" : ""
    },
    "meetingRooms" : [ {
      "roomId" : "c10315a8b4e740a317813ab6fxxxxxx",
      "responseStatus" : "accepted",
      "displayName" : "Meeting Room 1"
    } ]
  } ]
}

Error codes

If the API call fails, look up the solution in the Global error codes document based on the error message.

HttpCode	Error code	Error message	Description
400	invalidParameter	forwardErrorMessage	Invalid parameter

​API call description

​Request

​Basic information

​Request headers

​Path parameters

​Query parameters

​Request example

​Response

​Response body

​Response body example

​Error codes