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

# Retrieve Stroker Status

> Retrieve the current status of the stroker on the device.



## OpenAPI

````yaml /api-reference/openapi_sdk.yaml get /device/stroker/status
openapi: 3.1.0
info:
  title: Melody API
  contact:
    name: Melody Support
    email: support@getmelody.io
    url: https://docs.getmelody.io
  description: >
    # Introduction


    The Melody API controls a linked Melody Device: read its state, send motion
    commands, run scripted playback, and manage pairing.


    Unless an endpoint says otherwise, every request carries the header
    `Content-Type: application/json`.


    Base URL: [api.getmelody.io](https://api.getmelody.io)


    # Authentication


    Access is scoped to your **organization**. Your **Organization ID** and
    **Developer Key** are issued to you by Melody — contact
    [support@getmelody.io](mailto:support@getmelody.io) to request them.


    To call device endpoints:


    1. Link a device to your organization with `POST /device/otp/confirm/v2`
    (send your Developer Key in the `X-Org-Key` header) to obtain its **Device
    Key**.

    2. Exchange your Developer Key for a short-lived **session token** with
    `POST /api/sessions/v2`.

    3. Call any `/device/*` endpoint with `Authorization: Bearer
    <session_token>` and the `X-Device-Key: <device-key>` header.
  version: v4
servers:
  - url: https://api.getmelody.io
    description: Production
security: []
tags:
  - name: Authentication
    description: >
      Obtain and use organization-scoped access tokens. Your Organization ID and
      Developer Key are issued to you by Melody — contact support@getmelody.io
      to request them.
  - name: Device Information
    description: >
      Read the device's identity, status and current session, and read or change
      its settings and

      playback mode.
  - name: Haptic Direct Control
    description: |
      Set a target position and how long the stroker takes to reach it.
  - name: Haptic Points Stream
    description: >
      Stream arrays of points, each carrying a position and a timestamp on the
      sender's own

      timescale. The device works out stroke velocity from the gap between
      consecutive points, so at

      least two points are needed before the stroker moves.
  - name: Haptic Script Control
    description: >
      Upload a funscript, then drive playback from the server with start, stop,
      pause and seek. The

      server parses the script and pushes its points to the device.
  - name: Haptic Loop Control
    description: >
      Simple up-and-down stroking with no data points. Give a velocity and a low
      and high position,

      and the device loops within that range on its own.
  - name: One-Time Password
    description: >
      A one-time password links a device to an organization. It is valid for 15
      minutes.
  - name: Stroker
    description: >
      Read the stroker's live motion state and calibration bounds, and set the
      software limits it

      moves within.
  - name: Maintenance
    description: >
      Keep a device healthy and find out what it is doing:


      - Firmware updates: check for, download and apply a firmware update.

      - Debug information: read diagnostic counters such as free heap and flash
      size.

      - Debug Logging: Enable or disable real-time debug log emission from the
      device. When enabled, the device sends unsolicited `DEBUG_LOG` frames
      (frame type `21`) over the WebSocket. Each frame carries a
      `DebugLogMessage` protobuf payload with a single `message` string field.
      Logs are stored server-side per device, up to 1000 entries.
paths:
  /device/stroker/status:
    get:
      tags:
        - Stroker
      summary: Retrieve Stroker Status
      description: Retrieve the current status of the stroker on the device.
      operationId: get-device-stroker-status
      parameters:
        - $ref: '#/components/parameters/XDeviceKey'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceStrokerStatus'
      security:
        - SessionToken: []
components:
  parameters:
    XDeviceKey:
      name: X-Device-Key
      in: header
      required: true
      description: |
        Device Key (4 BIP39 words) identifying the target device.
        Obtain it from `POST /device/otp/confirm/v2`.
      schema:
        type: string
        pattern: ^[a-z]+-[a-z]+-[a-z]+-[a-z]+$
        example: orbit-ranch-silver-tomato
  schemas:
    DeviceStrokerStatus:
      type: object
      description: |
        The current status of the stroker on the device.
      properties:
        current_pos_angle:
          type: number
          format: float
          description: |
            The current position of the stroker in radians.
          example: 1.57
        current_pos_range:
          type: integer
          format: int32
          description: |
            The current position of the stroker in points.
          example: 5000
        target_pos_angle:
          type: number
          format: float
          description: |
            The target position of the stroker in radians.
          example: 3.14
        target_pos_range:
          type: integer
          format: int32
          description: |
            The target position of the stroker in points.
          example: 7500
        current_vel_angle:
          type: number
          format: float
          description: |
            The current velocity of the stroker in rad/s.
          example: 2.5
        current_vel_range:
          type: integer
          format: int32
          description: |
            The current velocity of the stroker in points/s.
          example: 30
  securitySchemes:
    SessionToken:
      type: http
      scheme: bearer
      description: >
        Short-lived session token obtained from POST /api/sessions/v2.

        Send it as `Authorization: Bearer <session_token>` together with the
        `X-Device-Key: <device-key>` header identifying the target device.

````