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

# Get Worker Time Punches

> Returns a paginated list of time punches for a worker.

<Info>
  This endpoint supports pagination via `items_per_page` and `page` query parameters.
</Info>

<Tip>
  Use the `date` parameter to filter punches for a specific date. When `date` is provided, it takes priority over `start_date` and `end_date`. Use `shift_id` to filter punches for a specific shift assignment.
</Tip>


## OpenAPI

````yaml api-reference/v01.12.00/openapi-v01.12.00.json GET /workers/{id}/time-punches
openapi: 3.0.0
info:
  title: Roosted
  version: 0.1.12
  contact:
    name: Support
    url: https://support.roostedhr.com/support/home
    email: support@roostedhr.com
  description: |-
    Enterprise API

    Sandbox keys and Production keys are requested from support
servers:
  - url: https://api.roostedhr.com/api/1_12
  - url: https://sandbox.roostedhr.com/api/1_12
security:
  - X-API-KEY: []
tags:
  - name: Announcements
  - name: Areas
  - name: Clients
  - name: Company
  - name: Configuration
  - name: Events
  - name: Locations
  - name: Payroll Groups
  - name: Rate Cards
  - name: Shifts
  - name: Skillsets
  - name: Time Tracking
  - name: Wage Rules
  - name: Workers
paths:
  /workers/{id}/time-punches:
    parameters:
      - schema:
          type: string
        name: id
        in: path
        required: true
        description: Worker ID
    get:
      tags:
        - Workers
      summary: Get Worker Time Punches
      description: Returns a paginated list of time punches for a worker.
      operationId: get-worker-time-punches
      parameters:
        - schema:
            type: string
            format: date
            example: '2026-03-17'
          name: date
          in: query
          description: >-
            Filter punches for a specific date. Takes priority over `start_date`
            and `end_date` when provided.
        - schema:
            type: string
            format: date
            example: '2026-01-01'
          name: start_date
          in: query
          description: Filter punches on or after this date. Ignored if `date` is provided.
        - schema:
            type: string
            format: date
            example: '2026-12-31'
          name: end_date
          in: query
          description: >-
            Filter punches on or before this date. Ignored if `date` is
            provided.
        - schema:
            type: string
          name: shift_id
          in: query
          description: Filter punches for a specific shift assignment.
        - schema:
            type: integer
            minimum: 1
            maximum: 100
          name: items_per_page
          in: query
          description: Number of items per page.
        - schema:
            type: integer
            minimum: 1
          name: page
          in: query
          description: Page number.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  time_punches:
                    type: array
                    description: List of worker time punches.
                    items:
                      $ref: '#/components/schemas/TimePunch'
                  total:
                    type: integer
                    description: Total number of time punches matching the filter criteria.
                    example: 32
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Machine-readable error code.
                  error:
                    type: string
                    description: Human-readable error message.
              examples:
                Invalid page parameter:
                  value:
                    code: WRK-2400
                    error: Invalid page parameter
                Invalid items per page parameter:
                  value:
                    code: WRK-2400
                    error: Invalid items per page parameter
                Invalid date range filter:
                  value:
                    code: WRK-2400
                    error: Invalid date range filter
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Machine-readable error code.
                  error:
                    type: string
                    description: Human-readable error message.
              examples:
                Invalid or missing API key:
                  value:
                    code: ATH-100
                    error: Invalid or missing API key
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Machine-readable error code.
                  error:
                    type: string
                    description: Human-readable error message.
              examples:
                Insufficient permissions to view worker time punches:
                  value:
                    code: WRK-2500
                    error: Insufficient permissions to view worker time punches
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Machine-readable error code.
                  error:
                    type: string
                    description: Human-readable error message.
              examples:
                Worker not found:
                  value:
                    code: WRK-300
                    error: Worker not found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: Machine-readable error code.
                  error:
                    type: string
                    description: Human-readable error message.
              examples:
                An unexpected error occurred:
                  value:
                    code: WRK-2600
                    error: An unexpected error occurred
components:
  schemas:
    TimePunch:
      title: TimePunch
      type: object
      description: >-
        A time punch record for a worker, including clock type, status, and
        associated shift details.
      properties:
        id:
          type: string
          description: Time punch ID.
          example: QNPdD
        p_id:
          type: string
          description: Worker ID.
          example: '3158'
        erf_id:
          type: string
          nullable: true
          description: Associated shift assignment ID.
          example: '2205477'
        ern_id:
          type: string
          nullable: true
          description: Associated shift role ID.
          example: '1442591'
        manager_id:
          type: string
          description: ID of the manager who processed the punch.
          example: '3158'
        events_roles_placeholders_id:
          type: string
          nullable: true
          description: Associated placeholder ID.
        latitude:
          type: string
          nullable: true
          description: GPS latitude of punch location.
        longitude:
          type: string
          nullable: true
          description: GPS longitude of punch location.
        source:
          type: string
          description: Source of the time punch.
          example: Manager
        punch_datetime:
          type: string
          description: Punch datetime in UTC.
          example: '2024-05-03 20:00:00'
        converted_punch_datetime:
          type: string
          description: Punch datetime converted to event timezone.
          example: '2024-05-03 15:00:00'
        status:
          type: string
          description: Punch status (e.g., `approved`, `pending`, `declined`).
          example: approved
        clock_picture_location:
          type: string
          nullable: true
          description: URL of the clock-in/out photo.
        insert_date:
          type: string
          description: Record creation datetime.
          example: '2024-04-30 13:57:28'
        override_max_shift_time:
          type: string
          description: Whether max shift time override is enabled.
          example: 'N'
        original_datetime:
          type: string
          nullable: true
          description: Original punch datetime before any edits.
        time_change_request:
          type: string
          nullable: true
          description: Requested time change value.
        time_change_request_submitted:
          type: string
          nullable: true
          description: Datetime the time change request was submitted.
        client_sign_datetime:
          type: string
          nullable: true
          description: Datetime the client signed off.
        delete_requested:
          type: string
          description: Whether deletion has been requested.
          example: '0'
        open:
          type: string
          description: Whether the punch is open (unpaired).
          example: '0'
        bad_location:
          type: string
          description: Whether the punch location was flagged.
          example: '0'
        client_name:
          type: string
          description: Associated client name.
          example: 'Test Client #1'
        client_invoice_customer_id:
          type: string
          description: Client invoice customer ID.
          example: '0123007'
        event_name:
          type: string
          description: Associated event name.
          example: Hello World
        location_id:
          type: string
          description: Location ID.
          example: '1503'
        location:
          type: string
          description: Location name.
          example: Arrowhead Stadium
        addy_city:
          type: string
          description: Location city.
          example: Kansas City
        timezone_name:
          type: string
          description: Event timezone.
          example: America/Chicago
        jobs_id:
          type: string
          description: Associated job ID.
          example: '677421'
        custom_event_id:
          type: string
          description: Custom event identifier.
        areas:
          type: string
          description: Associated areas.
        client_id:
          type: string
          description: Client ID.
          example: hAjwQ
        ern_start:
          type: string
          description: Shift start datetime.
          example: '2024-05-03 14:00:00'
        ern_date:
          type: string
          description: Shift date.
          example: '2024-05-03 14:00:00'
        ern_start_date:
          type: string
          description: Shift start date.
          example: '2024-05-03'
        nice_ern_start:
          type: string
          description: Formatted shift start time.
          example: 2:00 PM
        role_title:
          type: string
          description: Role title.
          example: Bartender
        ern_end:
          type: string
          description: Shift end datetime.
          example: '2024-05-23 00:00:00'
        payroll_groups_id:
          type: string
          description: Payroll group ID.
          example: gDrT7
        payroll_groups_name:
          type: string
          nullable: true
          description: Payroll group name.
        rate_cards_id:
          type: string
          nullable: true
          description: Rate card ID.
        rate_cards_name:
          type: string
          nullable: true
          description: Rate card name.
        signature_datetime:
          type: string
          nullable: true
          description: Manager signature datetime.
        signature_name:
          type: string
          nullable: true
          description: Manager signature name.
        signature_notes:
          type: string
          nullable: true
          description: Manager signature notes.
        signature_location:
          type: string
          nullable: true
          description: Manager signature location URL.
        worker_signature_location:
          type: string
          nullable: true
          description: Worker signature location URL.
        worker_signature_comments:
          type: string
          nullable: true
          description: Worker signature comments.
        worker_signature_datetime:
          type: string
          nullable: true
          description: Worker signature datetime.
        worker_signature_missing:
          type: boolean
          description: Whether the worker signature is missing.
          example: true
        travel_hours_before:
          type: string
          description: Travel hours before shift.
          example: '0.00'
        travel_hours_after:
          type: string
          description: Travel hours after shift.
          example: '0.00'
        timezone_data:
          type: string
          description: Timezone abbreviation.
          example: CDT
        nice_shiftedPunch:
          type: string
          description: Formatted punch time with timezone.
          example: 15:00 CDT May 3rd
        nice_shiftedPunch_ampm:
          type: string
          description: Formatted punch time with AM/PM.
          example: 3:00 pm CDT May 3rd
        punchDate:
          type: string
          description: Punch date.
          example: '2024-05-03'
        shiftedPunch:
          type: string
          description: Timezone-adjusted punch datetime.
          example: '2024-05-03 15:00:00'
        nicePunch:
          type: string
          description: Formatted punch time.
          example: 3:00 pm
        scheduledHours:
          type: integer
          description: Scheduled hours for the shift.
          example: 466
        clockType:
          type: string
          description: Clock type (`IN` or `OUT`).
          example: OUT
        in_punch:
          type: string
          description: Associated clock-in punch datetime.
          example: '2024-05-03 10:00:00'
        spot_wage:
          type: string
          nullable: true
          description: Spot wage rate.
        shift_wage:
          type: string
          nullable: true
          description: Shift wage rate.
        personnel_pay_rate:
          type: string
          nullable: true
          description: Personnel pay rate.
        client_pay_rate:
          type: string
          nullable: true
          description: Client pay rate.
        role_pay_rate:
          type: string
          nullable: true
          description: Role pay rate.
        spot_billing_rate:
          type: string
          nullable: true
          description: Spot billing rate.
        shift_billing:
          type: string
          nullable: true
          description: Shift billing rate.
        personnel_billing_rate:
          type: string
          nullable: true
          description: Personnel billing rate.
        client_billing_rate:
          type: string
          nullable: true
          description: Client billing rate.
        role_billing_rate:
          type: string
          nullable: true
          description: Role billing rate.
        possibleDuplicate:
          type: boolean
          description: Whether this punch may be a duplicate.
  securitySchemes:
    X-API-KEY:
      name: X-API-KEY
      type: apiKey
      in: header

````