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

# List Meals

> Returns meals (nutrition entries).



## OpenAPI

````yaml /openapi.json get /api/v1/users/{user_id}/events/meals
openapi: 3.1.0
info:
  title: Open Wearables API
  version: 0.9.0
servers: []
security: []
paths:
  /api/v1/users/{user_id}/events/meals:
    get:
      tags:
        - 'External: Events'
      summary: List Meals
      description: Returns meals (nutrition entries).
      operationId: list_meals_api_v1_users__user_id__events_meals_get
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: User Id
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            description: >-
              ISO 8601 datetime (e.g. `2023-11-07T05:31:56Z`) or Unix timestamp
              in seconds. Date-only strings (e.g. `2023-11-07`) are also
              accepted and cover the whole day, so a date-only range includes
              both boundary days.
            examples:
              - '2023-11-07T05:31:56Z'
              - '2023-11-07'
            format: date-time
            title: Start Date
          description: >-
            ISO 8601 datetime (e.g. `2023-11-07T05:31:56Z`) or Unix timestamp in
            seconds. Date-only strings (e.g. `2023-11-07`) are also accepted and
            cover the whole day, so a date-only range includes both boundary
            days.
        - name: end_date
          in: query
          required: true
          schema:
            type: string
            description: >-
              ISO 8601 datetime (e.g. `2023-11-07T05:31:56Z`) or Unix timestamp
              in seconds. Date-only strings (e.g. `2023-11-07`) are also
              accepted and cover the whole day, so a date-only range includes
              both boundary days.
            examples:
              - '2023-11-07T05:31:56Z'
              - '2023-11-07'
            format: date-time
            title: End Date
          description: >-
            ISO 8601 datetime (e.g. `2023-11-07T05:31:56Z`) or Unix timestamp in
            seconds. Date-only strings (e.g. `2023-11-07`) are also accepted and
            cover the whole day, so a date-only range includes both boundary
            days.
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Cursor
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 1000
            minimum: 1
            default: 50
            title: Limit
        - name: provider
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/ProviderName'
              - type: 'null'
            title: Provider
        - name: source
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Source
        - name: device_model
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Device Model
        - name: data_source_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            title: Data Source Id
        - name: X-Open-Wearables-API-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Open-Wearables-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_Meal_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2PasswordBearer: []
components:
  schemas:
    ProviderName:
      type: string
      enum:
        - apple
        - samsung
        - garmin
        - health_connect
        - google_health
        - polar
        - suunto
        - whoop
        - strava
        - oura
        - fitbit
        - ultrahuman
        - sensorbio
        - withings
        - unknown
        - internal
      title: ProviderName
      description: Supported data providers.
    PaginatedResponse_Meal_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Meal'
          type: array
          title: Data
        pagination:
          $ref: '#/components/schemas/Pagination'
        metadata:
          $ref: '#/components/schemas/TimeseriesMetadata'
      type: object
      required:
        - data
        - pagination
        - metadata
      title: PaginatedResponse[Meal]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Meal:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        timestamp:
          type: string
          format: date-time
          title: Timestamp
        meal_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Meal Type
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        source:
          $ref: '#/components/schemas/SourceMetadata'
        calories_kcal:
          anyOf:
            - type: number
            - type: 'null'
          title: Calories Kcal
        macros:
          anyOf:
            - $ref: '#/components/schemas/Macros'
            - type: 'null'
        water_ml:
          anyOf:
            - type: number
            - type: 'null'
          title: Water Ml
        nutrients:
          additionalProperties:
            $ref: '#/components/schemas/NutrientValue'
          type: object
          title: Nutrients
          description: >-
            All nutrient values recorded for the meal, keyed by series type
            (e.g. dietary_sugar)
          example:
            dietary_sugar:
              unit: g
              value: 12.5
      type: object
      required:
        - id
        - timestamp
        - source
      title: Meal
    Pagination:
      properties:
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: Cursor to fetch next page, null if no more data
          example: eyJpZCI6IjEyMzQ1Njc4OTAiLCJ0cyI6MTcwNDA2NzIwMH0
        previous_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Previous Cursor
          description: Cursor to fetch previous page
        has_more:
          type: boolean
          title: Has More
          description: Whether more data is available
        total_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total Count
          description: Total number of records matching the query
          example: 150
      type: object
      required:
        - has_more
      title: Pagination
    TimeseriesMetadata:
      properties:
        resolution:
          anyOf:
            - $ref: '#/components/schemas/Resolution'
            - type: 'null'
        sample_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Sample Count
        start_time:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Start Time
        end_time:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: End Time
      type: object
      title: TimeseriesMetadata
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    SourceMetadata:
      properties:
        provider:
          type: string
          title: Provider
          example: apple
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
          example: Connect
        device:
          anyOf:
            - type: string
            - type: 'null'
          title: Device
          example: iPhone15,2
        device_type:
          anyOf:
            - $ref: '#/components/schemas/DeviceType'
            - type: 'null'
          example: phone
        device_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Device Name
          description: >-
            Marketing name for ``device``, derived so it cannot drift from the
            raw model.
          readOnly: true
      type: object
      required:
        - provider
        - device_name
      title: SourceMetadata
    Macros:
      properties:
        protein_g:
          anyOf:
            - type: number
            - type: 'null'
          title: Protein G
        carbohydrates_g:
          anyOf:
            - type: number
            - type: 'null'
          title: Carbohydrates G
        fat_g:
          anyOf:
            - type: number
            - type: 'null'
          title: Fat G
        fiber_g:
          anyOf:
            - type: number
            - type: 'null'
          title: Fiber G
      type: object
      title: Macros
    NutrientValue:
      properties:
        value:
          type: number
          title: Value
        unit:
          type: string
          title: Unit
      type: object
      required:
        - value
        - unit
      title: NutrientValue
    Resolution:
      type: string
      enum:
        - raw
        - 1min
        - 5min
        - 15min
        - 1hour
      title: Resolution
      description: >-
        Bucket width requested when reading time series. RAW returns stored
        samples untouched.
    DeviceType:
      type: string
      enum:
        - watch
        - band
        - phone
        - scale
        - ring
        - tablet
        - chest_strap
        - hr_sensor
        - headphones
        - head_mounted
        - glasses
        - smart_display
        - bp_monitor
        - glucose_meter
        - thermometer
        - sleep_monitor
        - bike_computer
        - fitness_machine
        - other
        - unknown
      title: DeviceType
      description: Type of device that collected health data.
  securitySchemes:
    OAuth2PasswordBearer:
      type: oauth2
      flows:
        password:
          scopes: {}
          tokenUrl: /api/v1/auth/login

````

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