openapi: 3.0.2
info:
  description: Endpoints to create or update meters in bulk through Leap's API.
  title: create meters performance API
  version: 1.1.0
servers:
- description: Leap staging API
  url: https://api.staging.leap.energy
- description: Leap production API
  url: https://api.leap.energy
security:
- Bearer: []
tags:
- name: performance
paths:
  /v1.1/performance/diagnosis/monthly/unresponsive/meters:
    post:
      deprecated: false
      description: Retrieves unresponsive meters in a designated month
      operationId: postMonthlyUnresponsiveMetersPerformance
      parameters:
      - description: Boolean flag indicating whether the response should include  a summary of the requested data in addition to the detailed results.
        explode: true
        in: query
        name: include_summary
        required: false
        schema:
          default: false
          type: boolean
        style: form
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MonthlyUnresponsiveMetersRequest'
          text/csv:
            schema:
              type: string
        description: Monthly unresponsive meters request body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonthlyUnresponsiveMetersResponse'
          description: Retrieves monthly unresponsive meters for a specified month
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBadRequest'
          description: Returns 400 if the request is invalid.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseUnauthorized'
          description: Returns 401 if the request is unauthorized.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseForbidden'
          description: Returns 403 if the request doesn't have the right values.
        '415':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseUnsupportedMediaType'
          description: Returns 415 if provided content in the request is not supported.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseInternalServerError'
          description: Returns 500 if the there's an internal server error.
      security:
      - Bearer: []
      summary: Monthly unresponsive meters
      tags:
      - performance
components:
  schemas:
    ErrorResponseDetail:
      additionalProperties: false
      example:
        message: message
        description: description
      properties:
        message:
          type: string
        description:
          type: string
      required:
      - description
      - message
      type: object
    ErrorResponseUnauthorized:
      additionalProperties: false
      example:
        title: Unauthorized
        status: 401
        details:
        - message: message
          description: description
        - message: message
          description: description
      properties:
        title:
          example: Unauthorized
          type: string
        status:
          example: 401
          format: int32
          type: integer
        details:
          items:
            $ref: '#/components/schemas/ErrorResponseDetail'
          type: array
      required:
      - details
      - status
      - title
      type: object
    SortDirection:
      description: Sort direction for a field. Can be `ASC` for ascending or `DESC` for descending.
      enum:
      - ASC
      - DESC
      type: string
    UnresponsiveMeter:
      example:
        meter_id: db0291d1-009d-4393-9a8d-4613a4efcd7a
        partner_reference: partner_reference
        customer_name: John Doe
        customer_group: Store Inc.
        transmission_region: CAISO
        program: CEC-DSGS
        missed_revenue: 20000.3
        nomination_w: 16600.88
        response_percentage: 75
        number_of_events: 6
        historical_responsiveness: NEVER_RESPONDS
      properties:
        meter_id:
          description: Meter UUID
          example: db0291d1-009d-4393-9a8d-4613a4efcd7a
          format: uuid
          type: string
        partner_reference:
          description: Meter partner reference.
          type: string
        customer_name:
          description: Customer Name
          example: John Doe
          type: string
        customer_group:
          description: 'The Customer Group(s) associated with the customer. If the customer is part of multiple groups, they will be separated by a comma.

            '
          example: Store Inc.
          type: string
        transmission_region:
          $ref: '#/components/schemas/transmission_region'
        program:
          $ref: '#/components/schemas/program_identifier'
        missed_revenue:
          description: 'The difference between potential revenue and the actual revenue of the revenue report over the settlement period. Rounded to zero if actual revenue is greater than potential revenue.

            '
          example: 20000.3
          format: double
          type: number
        nomination_w:
          description: Target quantity set for capacity market.
          example: 16600.88
          format: double
          type: number
        response_percentage:
          description: The meter?s event response percentage.
          example: 75
          format: double
          type: number
        number_of_events:
          description: Total number of events.
          format: int32
          type: integer
        historical_responsiveness:
          $ref: '#/components/schemas/HistoricalResponsiveness'
      required:
      - historical_responsiveness
      - meter_id
      - number_of_events
      - program
      - response_percentage
      - transmission_region
      type: object
    MeterProgram:
      example:
        program: CEC-DSGS
        meter_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
      properties:
        program:
          $ref: '#/components/schemas/program_identifier'
        meter_id:
          format: uuid
          type: string
      required:
      - meter_id
      - program
      type: object
    ErrorResponseUnsupportedMediaType:
      additionalProperties: false
      example:
        title: Unsupported Media Type
        status: 415
        details:
        - message: Invalid value in the 'Accept' header.
          description: Supported types are application/json and text/csv
      properties:
        title:
          example: Unsupported Media Type
          type: string
        status:
          example: 415
          format: int32
          type: integer
        details:
          example:
          - message: Invalid value in the 'Accept' header.
            description: Supported types are application/json and text/csv
          items:
            $ref: '#/components/schemas/ErrorResponseDetail'
          type: array
      required:
      - details
      - status
      - title
      type: object
    HistoricalResponsiveness:
      description: Shows the meter?s responsiveness for the last 12 months.
      enum:
      - NEVER_RESPONDS
      - RARELY_RESPONDS
      - NORMALLY_RESPONDS
      - NEW_METER
      type: string
    MonthlyUnresponsiveMetersResponse:
      example:
        summary:
          number_of_meters: 0
          missed_revenue: 20000.3
          average_response_percentage: 75
        meters:
        - meter_id: db0291d1-009d-4393-9a8d-4613a4efcd7a
          partner_reference: partner_reference
          customer_name: John Doe
          customer_group: Store Inc.
          transmission_region: CAISO
          program: CEC-DSGS
          missed_revenue: 20000.3
          nomination_w: 16600.88
          response_percentage: 75
          number_of_events: 6
          historical_responsiveness: NEVER_RESPONDS
        - meter_id: db0291d1-009d-4393-9a8d-4613a4efcd7a
          partner_reference: partner_reference
          customer_name: John Doe
          customer_group: Store Inc.
          transmission_region: CAISO
          program: CEC-DSGS
          missed_revenue: 20000.3
          nomination_w: 16600.88
          response_percentage: 75
          number_of_events: 6
          historical_responsiveness: NEVER_RESPONDS
        year_month: 2023-03
        page_token: page_token
      properties:
        summary:
          $ref: '#/components/schemas/UnresponsiveMetersSummary'
        meters:
          items:
            $ref: '#/components/schemas/UnresponsiveMeter'
          type: array
        year_month:
          description: ISO-8601 formatted year and month (`YYYY-MM`) representing the performance diagnosis month.
          example: 2023-03
          pattern: ^\d{4}-\d{2}$
          type: string
        page_token:
          description: 'If there are more records to fetch, this token will be populated as `next_page_token` in the response. Use it to fetch the next page. When requesting a CSV format via Accept header with value `text/csv`, this parameter is not required.

            '
          type: string
      required:
      - meters
      type: object
    ErrorResponseForbidden:
      additionalProperties: false
      example:
        title: Forbidden
        status: 403
        details:
        - message: message
          description: description
        - message: message
          description: description
      properties:
        title:
          example: Forbidden
          type: string
        status:
          example: 403
          format: int32
          type: integer
        details:
          items:
            $ref: '#/components/schemas/ErrorResponseDetail'
          type: array
      required:
      - details
      - status
      - title
      type: object
    program_identifier:
      description: Identifier of program
      enum:
      - CAISO-CCA-SC_ONLY
      - CAISO-HOLD_OPEN
      - CCA
      - CEC-DSGS-OPTION4
      - CEC-DSGS
      - CONED-CSRP
      - CONED-DLRP
      - DRAM
      - ELRP
      - ENERGY-ONLY
      - ERCOT-ERS
      - EVERSOURCE-CS
      - MA_DOER-CPS
      - NATGRID-CS
      - NRG-REALTIME
      - NRG-RED
      - NYISO-SCR
      - ONCOR-CLM
      - PGE-ART
      - PGE-CBP
      - PJM-CAPACITY
      - PSEGLI-CSRP
      - PSEGLI-DLRP
      - RIE-CS
      - UNITIL-CS
      - PSE-RPO
      - SRP-RPO
      - TVA-RPO
      - CAISO-ELRP-A4
      - CEC-DSGS-OPTION2
      - ENERGYHUB-CS
      - CT_GB-ESS
      example: CEC-DSGS
      type: string
    transmission_region:
      description: Defines the transmission region of the meter
      enum:
      - CAISO
      - ERCOT
      - NYISO
      - ISONE
      - PJM
      - SERC
      - WECC_SW
      - WECC_PC
      example: CAISO
      type: string
    ErrorResponseInternalServerError:
      additionalProperties: false
      example:
        title: Server Error
        status: 500
        details:
        - message: Internal Error
          description: A technical error has occurred
      properties:
        title:
          example: Server Error
          type: string
        status:
          example: 500
          format: int32
          type: integer
        details:
          example:
          - message: Internal Error
            description: A technical error has occurred
          items:
            $ref: '#/components/schemas/ErrorResponseDetail'
          type: array
      required:
      - details
      - status
      - title
      type: object
    UnresponsiveMetersSummary:
      example:
        number_of_meters: 0
        missed_revenue: 20000.3
        average_response_percentage: 75
      properties:
        number_of_meters:
          description: Total number of unresponsive meters.
          format: int32
          type: integer
        missed_revenue:
          description: 'The difference between potential revenue and the actual revenue of the revenue report over the settlement period. Rounded to zero if actual revenue is greater than potential revenue.

            '
          example: 20000.3
          format: double
          type: number
        average_response_percentage:
          description: Monthly average response percentage for meters.
          example: 75
          format: double
          type: number
      type: object
    ErrorResponseBadRequest:
      additionalProperties: false
      example:
        title: Bad Request
        status: 400
        details:
        - message: Validation Error
          description: Missing required parameter(s)
      properties:
        title:
          example: Bad Request
          type: string
        status:
          example: 400
          format: int32
          type: integer
        details:
          example:
          - message: Validation Error
            description: Missing required parameter(s)
          items:
            $ref: '#/components/schemas/ErrorResponseDetail'
          type: array
      required:
      - details
      - status
      - title
      type: object
    SortRequest:
      additionalProperties: false
      properties:
        field:
          description: The field used to perform the sort operation
          example: nomination_w
          type: string
        direction:
          $ref: '#/components/schemas/SortDirection'
      required:
      - direction
      - field
      type: object
    MonthlyUnresponsiveMetersRequest:
      example:
        year_month: 2023-03
        meter_id_contains: meter_id_contains
        partner_reference_contains: partner_reference_contains
        customer_name_contains: customer_name_contains
        transmission_regions:
        - CAISO
        - CAISO
        programs:
        - CEC-DSGS
        - CEC-DSGS
        historical_responsiveness:
        - NEVER_RESPONDS
        - NEVER_RESPONDS
        include_meter_programs:
        - program: CEC-DSGS
          meter_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        - program: CEC-DSGS
          meter_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        - program: CEC-DSGS
          meter_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        - program: CEC-DSGS
          meter_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        - program: CEC-DSGS
          meter_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        exclude_meter_programs:
        - program: CEC-DSGS
          meter_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        - program: CEC-DSGS
          meter_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        - program: CEC-DSGS
          meter_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        - program: CEC-DSGS
          meter_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        - program: CEC-DSGS
          meter_id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        page_token: page_token
        page_size: 100
        sort:
        - direction: DESC
          field: nomination_kw
        - direction: ASC
          field: meter_id
      properties:
        year_month:
          description: ISO-8601 formatted year and month (`YYYY-MM`) representing the performance diagnosis month.
          example: 2023-03
          pattern: ^\d{4}-\d{2}$
          type: string
        meter_id_contains:
          description: Filters meters whose id contains the specified substring.
          type: string
        partner_reference_contains:
          description: Filters meters whose partner reference contains the specified substring.
          type: string
        customer_name_contains:
          description: Filters meters whose customer name contains the specified substring.
          type: string
        transmission_regions:
          description: Filters meters whose transmission region is in the specified list of transmission regions.
          items:
            $ref: '#/components/schemas/transmission_region'
          type: array
        programs:
          description: Filters meters whose program is in the specified list of programs.
          items:
            $ref: '#/components/schemas/program_identifier'
          type: array
        historical_responsiveness:
          description: Filters meters whose historical responsiveness is in the specified list of historical responsiveness.
          items:
            $ref: '#/components/schemas/HistoricalResponsiveness'
          type: array
        include_meter_programs:
          description: List of meter UUID, program pairs to include in the response.
          items:
            $ref: '#/components/schemas/MeterProgram'
          maxItems: 100
          type: array
        exclude_meter_programs:
          description: List of meter UUID, program pairs to exclude from the response.
          items:
            $ref: '#/components/schemas/MeterProgram'
          maxItems: 100
          type: array
        page_token:
          description: 'If there are more records to fetch, this token will be populated as `next_page_token` in the response. Use it to fetch the next page. When requesting a CSV format via Accept header with value `text/csv`, this parameter is not required.

            '
          type: string
        page_size:
          default: 100
          description: 'Specifies the number of results to return. Defaults to 100 if not set, with a maximum limit of 1000 per page. When requesting a CSV format via Accept header with value ''text/csv'', this parameter is not required.

            '
          example: 100
          format: int32
          type: integer
        sort:
          description: 'Specifies the sorting criteria for the results. It is a list of fields by which the results should be sorted. This parameter is optional. Supported for meter_id, partner_reference, customer_name, customer_group, transmission_region, program, missed_revenue, nomination_kw, response_percentage, number_of_events, historical_responsiveness fields.

            '
          example:
          - direction: DESC
            field: nomination_kw
          - direction: ASC
            field: meter_id
          items:
            $ref: '#/components/schemas/SortRequest'
          type: array
      required:
      - year_month
      type: object
  securitySchemes:
    Bearer:
      scheme: bearer
      type: http