> ## Documentation Index > Fetch the complete documentation index at: https://developers.lucca.fr/llms.txt > Use this file to discover all available pages before exploring further. # List WorkCycleExceptions. > Retrieve a paginated list of WorkCycleExceptions that satisfy the given query filters. ## OpenAPI ````yaml /openapi-specs/schedule.yaml get /api/v3/workcycleExceptions openapi: 3.1.0 info: title: Time Settings API version: '1.0' description: | Welcome on the documentation for the Time Settings API. contact: name: API Support url: https://support.lucca.fr email: contact@luccasoftware.com license: name: Unlicensed url: https://www.luccasoftware.com servers: - url: https://{host} description: Your Lucca account URL. variables: host: default: example.ilucca.net description: >- The URL of your dedicated Lucca account: `{account}.{env}.{region}`. Account reflects your company name. Env indicates the environment. Region depends on your server location. **Please, use your test or sandbox environments (and not your production env.) for testing purposes.** Environments: - `ilucca`: production environment for customers. - `ilucca-test`: test environment for customers. - `ilucca-demo`: demo environment for prospects. Regions: - `.ch` for Swiss located accounts. - `.net` for the others. Regarding sandboxes, the pattern differs: `https://{account}-{sandboxName}.sandbox.{server}.luccasoftware.com`, where: - `{sandboxName}` is automatically generated upon creation. - `{server}` may be "eu1", "eu2" or "ch1". security: [] tags: - name: UserDates description: Aggregates work schedule events. - name: WorkCycleExceptions description: Override an employee's theoretical working hours. - name: Working Time Arrangements description: Employees recurring working hours. - name: Collective Schedules description: Describes the working hours pattern of a working-time-arrangement. - name: employee-assignments description: Assignations of employees to working time arrangements. paths: /api/v3/workcycleExceptions: parameters: - $ref: '#/components/parameters/Authorization' get: tags: - WorkCycleExceptions summary: List WorkCycleExceptions. description: | Retrieve a paginated list of WorkCycleExceptions that satisfy the given query filters. operationId: list-workcycle-exceptions parameters: - name: fields in: query description: > List the properties you want included in the response. Example: `?fields=id,ownerId,isAm,startsAt,duration,unit,createdAt,modifiedAt,deletedAt,collection.count` The `collection.count` field indicates the total number of items across all pages. style: form explode: false schema: type: array items: type: string enum: - id - name - url - ownerId - owner.id - owner.name - owner.url - owner.firstName - owner.lastName - isAm - unit - startsAt - endsAt - durationInMinutes - duration - authorId - createdAt - modifierId - modifiedAt - deletedById - deletedAt - collection.count default: - id - name - url example: - id - ownerId - isAm - startsAt - duration - unit - createdAt - modifiedAt - deletedAt - name: id in: query description: > Retrieve WorkCycleExceptions that match one of the given IDs (comma separated list). style: form explode: false schema: type: array uniqueItems: true items: type: integer format: int32 minimum: 1 - name: ownerId in: query description: | Only retrieve WorkCycleExceptions that apply to one of the given employees, identified by their ID (comma separated list of int). style: form explode: false schema: type: array uniqueItems: true items: type: integer format: int32 minimum: 1 - name: isAm in: query description: > Filter on the `isAm` property. - `true`: the workcycleException applies to the first half-day. - `false`: the workcycleException applies to the second half-day. Omit this query parameter in order to retrieve all workcycleExceptions, whether they apply to the first or the second half-day. schema: type: boolean - name: startsAt in: query description: > Only retrieve items that match the given date condition. - `?startsAt=between,{date1},{date2}`: items that intersect the {date1}- {date2} period. - `?startsAt=since,{date}`: items that occur after (non-strict) the given {date}. - `?startsAt=until,{date}`: items that occur before (non-strict) the given {date}. schema: type: string examples: - between,2023-01-01,2023-12-31 - since,2023-01-01 - until,2023-12-31 - name: deletedAt in: query description: > - `null` (default): do no include deleted WorkCycleExceptions. - `notequal,null`: only retrieve deleted WorkCycleExceptions. - no param: retrieve both deleted and non-deleted WorkCycleExceptions. schema: type: string enum: - notequal,null - 'null' - name: unit in: query description: | Only retrieve WorkCycleExceptions whose unit match one of the given. schema: $ref: '#/components/schemas/EventUnit.v3' - name: paging in: query description: | Syntax: `{index},{pageSize}` Index is the position of the first item to retrieve. PageSize is the number of items per page. **Note**: Page size cannot exceed 1,000. For example, to retrieve the first 100 items: `?paging=0,100`, then to retrieve the 100 next: `?paging:100,100` schema: type: string - name: orderBy in: query style: form explode: false description: | Sort items by ascending or descending property value. Syntax is: `{propertyName},{direction}` where `direction` can either be `asc` (ascending) or `desc` (descending). schema: type: array items: type: string enum: - id,asc - id,desc - startsAt,asc - startsAt,desc default: - id,asc responses: '200': description: OK content: application/json: schema: type: object properties: data: type: object properties: count: type: integer format: int32 minimum: 0 items: type: array minItems: 0 items: $ref: '#/components/schemas/WorkCycleException' '400': $ref: '#/components/responses/ResponseProblem' '401': $ref: '#/components/responses/ResponseProblem' '404': $ref: '#/components/responses/ResponseProblem' '500': $ref: '#/components/responses/ResponseProblem' components: parameters: Authorization: name: Authorization required: true description: 'API key. Value must be formatted like so: `lucca application={api_key}`.' in: header schema: type: string schemas: EventUnit.v3: title: EventUnit type: integer format: int32 description: | A (work) event can be defined in one of 3 units. The unit must conform to the one defined by the applicable work-cycle of the given employee for the given date. - `0`: "days", the event duration is defined as a fraction of a (work) day. - `1`: "hours", the event duration is defined as a number of hours. - `2`: "time", the event duration is defined as a number of hours, at the time component of the `startsAt` property indicates the starting time. enum: - 0 - 1 - 2 WorkCycleException: title: The WorkCycleException resource x-tags: - WorkCycleExceptions description: > **Represents an override to the employee's WorkCycle.** **A workcycle is a setup object that indicates the working hours of one or several employees with a recurring pattern (weekly, monthly, etc...).** Workcycles are the basis from where employee's expected working hours are calculated. On top of it, holidays are first added,then workcycleExceptions. WorkCycleExceptions are overrides to the workcycles. The semantics of a workcycleException is equivalent to "exceptionally, this employee is going to work a different number of hours on this given half-day". A workcycleException may set the work duration to zero, thus indicating that the employee is not expected to work on this day. ❗**Note**: An employee may only have a **single** `WorkCycleException` on any given half-day (indicated by the `startsAt` date and the `isAm` boolean). ❗**Note 2**: When using Lucca Timesheet, submitting a timesheet actually "locks" the theoretical working hours of the employee. This means that creating or deleting workcycleExceptions on a day that belongs to a submitted timesheet will automatically unapprove said timesheet. A `WorkCycleException` must be defined in one "unit" (days, hours or time). This unit must be conform to the one of the intersecting WorkCycle for the employee and the date. Examples: **"User #12, managed in "days" (`unit: 0`), will finally work on the afternoon of the 01/01/2023"** ``` {"startsAt": "2023-01-01T12:00", "isAm": false, "duration": "12:00:00", "unit": 0} ``` **"User #13, managed in "hours" (`unit: 1`), will finally work 3h30 on the morning of the 01/01/2023"** ``` {"startsAt": "2023-01-01T00:00:00", "isAm": true, "duration": "03:30:00", "unit": 1} ``` **"User #14, managed in "time" unit (`unit: 2`), will finally work between 09:00 and 12:30 on the morning of the 01/01/2023"** ``` {"startsAt": "2023-01-01T09:00:00", "isAm": true, "duration": "03:30:00", "unit": 2} ``` type: object required: - id - ownerId - isAm - unit - startsAt - duration properties: id: type: integer format: int32 minimum: 1 description: Identifier of this WorkCycleException. readOnly: true name: type: string readOnly: true url: type: string format: uri readOnly: true ownerId: type: integer format: int32 minimum: 1 description: | Identifier of the employee. owner: type: object readOnly: true properties: id: type: integer format: int32 minimum: 1 name: type: string description: Full name of the employee. url: type: string format: uri description: URL to the employee representation. firstName: type: string description: First name of the employee. lastName: type: string description: Last name of the employee. isAm: type: boolean description: | A work day is divided into two half-days. Indicates whether the exception overrides the planned working hours of the first or the second half-day. - `true`: The exception overrides the first half-day (i.e. "morning"). - `false`: The exception overrides the second half-day (i.e. "afternoon"). unit: $ref: '#/components/schemas/EventUnit' startsAt: type: string format: date-time endsAt: type: string format: date-time readOnly: true durationInMinutes: type: integer format: int32 minimum: 0 readOnly: true duration: type: string format: time authorId: type: integer format: int32 minimum: 0 description: | The ID of the user who created this object. Equal to zero when created by an API key. readOnly: true createdAt: type: string format: date-time description: The timestamp of the moment this object was created. readOnly: true modifierId: type: integer format: int32 minimum: 0 description: | The ID of the user who last modified this object. Equal to zero when created by an API key. readOnly: true modifiedAt: type: string format: date-time description: The timestamp of the moment this object was last modified. readOnly: true deletedById: type: integer format: int32 minimum: 0 description: | The ID of the user who deleted this object. Equal to zero when created by an API key. readOnly: true deletedAt: type: string format: date-time description: The timestamp of the moment this object was deleted. readOnly: true EventUnit: title: Event Unit (enum) x-internal: true x-tags: - Core type: string enum: - day - hour - time description: |- An event can be set in: - Day: "I worked for a half day last Monday". - Hour: "I worked for 2 hours last Monday". - Time: "I worked between 10:00 AM and 12:00 AM last Monday". responses: ResponseProblem: description: Problem content: application/json: schema: type: object properties: Status: type: integer description: HTTP status code. example: 401 Message: type: string description: Human readable error message. example: Unauthorized ````