> ## Documentation Index > Fetch the complete documentation index at: https://docs.datanumia.com/llms.txt > Use this file to discover all available pages before exploring further. # Get challenges (depending on the provided site and filters) > This API returns : - a filtered, ordered and sorted list of challenges - the date of engagement, i.e. the date when the site engaged (if the site didn't engage, the date is not returned) - the number of sites participating in the challenge (the number of engaged sites) - the actual consumption since the date of engagement - the forecasted consumption ## OpenAPI ````yaml /api-reference/green-actions.yaml get /sites/{site-id}/challenges openapi: 3.0.1 info: title: Challenges lifecycle description: > This API manages the lifecycles of the challenges, the actions and the user engagements. termsOfService: '' version: 1.0.x servers: - url: https://api.home.datanumia.com/api/v1 security: [] paths: /sites/{site-id}/challenges: get: tags: - Challenge summary: Get challenges (depending on the provided site and filters) description: > This API returns : - a filtered, ordered and sorted list of challenges - the date of engagement, i.e. the date when the site engaged (if the site didn't engage, the date is not returned) - the number of sites participating in the challenge (the number of engaged sites) - the actual consumption since the date of engagement - the forecasted consumption operationId: getChallenges parameters: - name: site-id in: path description: The site identifier required: true schema: type: string - name: minBeginDate in: query description: The minimal begin date schema: type: string - name: maxBeginDate in: query description: The maximal begin date schema: type: string - name: minEndDate in: query description: The minimal end date schema: type: string - name: maxEndDate in: query description: The maximal end date schema: type: string - name: challengeFamily in: query description: The challenge family schema: type: string - name: challengeType in: query description: The challenge type schema: $ref: '#/components/schemas/ChallengeType' - name: limit in: query description: The limit of challenge to retrieve schema: type: number - name: orderBy in: query description: Order and sort challenge by date schema: type: string enum: - BEGIN_DATE_ASC - BEGIN_DATE_DESC - END_DATE_ASC - END_DATE_DESC responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/GetChallengesResponse' '400': description: Functional Error content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' '500': description: Technical Error content: application/json: schema: $ref: '#/components/schemas/ProblemDetail' components: schemas: ChallengeType: type: string enum: - PEAK_DAY - REWARD_DAY - SHIFT_DAY - PERIOD - MARATHON - SPRINT - VARIATION_CONSUMPTION_DAY - REDUCE_CONSUMPTION_DAY - OVER_CONSUMPTION_DAY GetChallengesResponse: required: - units - challenges - limit - orderBy type: object properties: units: $ref: '#/components/schemas/ConsumptionUnits' challenges: minItems: 0 type: array description: The list of challenges items: $ref: '#/components/schemas/GetChallengeResponse' limit: type: number description: limit of challenges received example: 5 orderBy: type: string description: challenges ordered and sorted by field example: BEGIN_DATE_ASC enum: - BEGIN_DATE_ASC - BEGIN_DATE_DESC - END_DATE_ASC - END_DATE_DESC ProblemDetail: required: - type - status properties: type: type: object title: type: string description: The problem title status: type: integer description: The problem status detail: type: string description: The problem detail instance: type: object description: The problem instance. By default, the request path properties: type: object description: A generic map of properties description: Representation for an RFC 7807 problem detail ConsumptionUnits: description: Units by type of consumption required: - energyMeter - cost properties: energyMeter: type: string default: KWH cost: type: string default: EUR GetChallengeResponse: required: - beginDate - challengeFamily - challengeId - challengeType - endDate type: object properties: challengeId: type: string description: The challenge identifier example: CHALLENGE_SPRINT_2023_10 parentChallengeId: type: string description: The parent challenge identifier example: CHALLENGE_MARATHON_2023_10 challengeFamily: type: string description: The challenge family example: MY_CHALLENGE_FAMILY challengeType: $ref: '#/components/schemas/ChallengeType' beginDate: type: string description: The challenge starting date, format YYYY-MM-DD example: '2023-10-01' endDate: type: string description: The challenge ending date, format YYYY-MM-DD example: '2024-01-01' engagementStatus: type: string description: The engagement status example: ENGAGED enum: - ENGAGED - MANUALLY_DISENGAGED - REMOVED_CONSENT engagementDate: type: string description: The site engagement starting date, format YYYY-MM-DD example: '2023-10-10' disengagementDate: type: string description: The site disengagement date, format YYYY-MM-DD example: '2023-11-10' minEngagementDate: type: string description: The min engagement date, format YYYY-MM-DD example: '2023-10-01' maxEngagementDate: type: string description: The max engagement date, format YYYY-MM-DD example: '2023-12-01' engagementsNumber: type: number description: >- The number of engaged sites in challenge with engagementStatus is in (ENGAGED, MISSING_REFERENCE_DATA) example: 1200 maxEngagementsNumber: type: number description: The maximum allowed number of engaged sites in challenge example: 1200 requiredContractExistenceInMonths: type: number description: The required months number to be engaged in challenge example: 12 status: type: string description: The removed consumption status example: KO enum: - OK - KO reason: type: string description: The removed consumption status example: REAL_NOT_RECEIVED actualConsumption: $ref: '#/components/schemas/Consumption' estimatedConsumption: $ref: '#/components/schemas/Consumption' removedConsumption: $ref: '#/components/schemas/Consumption' removedConsumptionPercentage: type: number description: The required months number to be engaged in challenge example: 12 removalSuccessThreshold: type: number description: >- The percentage of consumption reduction beyond which an commitment is considered successful. example: 10.5 consumptionTarget: $ref: '#/components/schemas/Consumption' consumptionPeriod: $ref: '#/components/schemas/ZonedTimePeriod' Consumption: required: - energyMeter - cost properties: energyMeter: $ref: '#/components/schemas/ConsumptionEnergyMeter' cost: $ref: '#/components/schemas/ConsumptionCost' ZonedTimePeriod: type: object properties: beginTs: type: string format: date-time example: '2023-05-01T00:00:00+02:00' endTs: type: string format: date-time example: '2023-05-06T00:00:00+02:00' ConsumptionEnergyMeter: required: - total properties: total: type: number description: The value of energy consumption example: 10.38 ConsumptionCost: required: - total properties: total: type: number description: The value of consumption cost example: 20.23 ````