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

# Filter steps by SQL condition (paginated)

> Filter measurement steps by a SQL WHERE condition and return
step counts.

Returns one page of matching step counts. Use limit <= 1000 and
repeat with increasing offset until fewer than limit rows are
returned to fetch all matches.

This endpoint allows filtering steps using SQL syntax and returns
the step counts from matching steps. Useful for finding specific
steps with certain characteristics (e.g., "find all 1-hour
discharge steps").

Match modes:
- "step" (default): Return only steps that match the condition
- "cycle": Return ALL steps from cycles that have at least one
  step matching the condition (useful for getting complete cycles)

Available columns for filtering:
- duration_s: Step duration in seconds
- cycle_count, step_count: Cycle and step numbers
- charge_capacity_ah, discharge_capacity_ah: Capacities
- charge_energy_wh, discharge_energy_wh: Energies
- min_voltage_v, max_voltage_v, mean_voltage_v: Voltage stats
- min_current_a, max_current_a, mean_current_a: Current stats
- And more (see MeasurementStepBase schema)

Example queries:
- duration_s >= 3600  (steps lasting 1+ hour)
- charge_capacity_ah > 1.5
- duration_s BETWEEN 1800 AND 7200



## OpenAPI

````yaml https://api.ionworks.com/openapi.json get /cell_measurements/{measurement_id}/filter-steps
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.ionworks.com
    description: Production
security: []
paths:
  /cell_measurements/{measurement_id}/filter-steps:
    get:
      tags:
        - Cell Measurements
      summary: Filter steps by SQL condition (paginated)
      description: |-
        Filter measurement steps by a SQL WHERE condition and return
        step counts.

        Returns one page of matching step counts. Use limit <= 1000 and
        repeat with increasing offset until fewer than limit rows are
        returned to fetch all matches.

        This endpoint allows filtering steps using SQL syntax and returns
        the step counts from matching steps. Useful for finding specific
        steps with certain characteristics (e.g., "find all 1-hour
        discharge steps").

        Match modes:
        - "step" (default): Return only steps that match the condition
        - "cycle": Return ALL steps from cycles that have at least one
          step matching the condition (useful for getting complete cycles)

        Available columns for filtering:
        - duration_s: Step duration in seconds
        - cycle_count, step_count: Cycle and step numbers
        - charge_capacity_ah, discharge_capacity_ah: Capacities
        - charge_energy_wh, discharge_energy_wh: Energies
        - min_voltage_v, max_voltage_v, mean_voltage_v: Voltage stats
        - min_current_a, max_current_a, mean_current_a: Current stats
        - And more (see MeasurementStepBase schema)

        Example queries:
        - duration_s >= 3600  (steps lasting 1+ hour)
        - charge_capacity_ah > 1.5
        - duration_s BETWEEN 1800 AND 7200
      operationId: >-
        filter_steps_by_condition_cell_measurements__measurement_id__filter_steps_get
      parameters:
        - name: measurement_id
          in: path
          required: true
          schema:
            type: string
            title: Measurement Id
        - name: where_clause
          in: query
          required: true
          schema:
            type: string
            description: 'SQL WHERE clause to filter steps. Example: duration_s >= 3600'
            title: Where Clause
          description: 'SQL WHERE clause to filter steps. Example: duration_s >= 3600'
        - name: match_mode
          in: query
          required: false
          schema:
            type: string
            description: >-
              How to match steps. 'step' returns only steps matching the
              condition. 'cycle' returns ALL steps from cycles that have at
              least one step matching the condition.
            default: step
            title: Match Mode
          description: >-
            How to match steps. 'step' returns only steps matching the
            condition. 'cycle' returns ALL steps from cycles that have at least
            one step matching the condition.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 1000
            minimum: 1
            description: Number of step counts to return per page (max 1000).
            default: 1000
            title: Limit
          description: Number of step counts to return per page (max 1000).
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            description: Number of step counts to skip for pagination.
            default: 0
            title: Offset
          description: Number of step counts to skip for pagination.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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

````