> ## 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. # Retrieve control scenario executions history for a site > This API is used to get control scenarios executions history for a site. ## OpenAPI ````yaml /api-reference/control-scenario-api-v2.yaml get /sites/{site-id}/control-scenarios/executions openapi: 3.0.1 info: title: control-scenario-api-v2 description: > Datanumia offers the ability automatically or manually control connected devices to optimize energy consumption. Automatic scenarios are pre-programmed optimizations used to reduce consumption for a specific scenario and triggered by events according to end-users contracts (peak days, bonus days...). When events are received, end-users devices are controlled automatically. In the other hand, Manual scenarios are pre-programmed optimizations used to reduce consumption and triggered manually by end-users actions. For example, end-users can set their accommodations to an AWAY mode for maximum reduction when they are away from their home instantly. To make this possible, Datanumia provides the services listed below : - Service to get control scenario executions history termsOfService: '' version: 3.43.0 servers: - url: https://api.home.datanumia.com/api/v2 security: [] paths: /sites/{site-id}/control-scenarios/executions: get: tags: - Control scenarios executions summary: Retrieve control scenario executions history for a site description: | This API is used to get control scenarios executions history for a site. operationId: getControlScenariosExecutions parameters: - name: site-id in: path description: Site identifier. required: true schema: type: string - name: scenarioId in: query description: Control scenario identifier. required: false schema: type: string - name: beginTs in: query description: The minimal begin date, format ISO8601 (YYYY-MM-DDThh:mm:ssZ) required: true schema: type: string - name: endTs in: query description: The maximal begin date, format ISO8601 (YYYY-MM-DDThh:mm:ssZ) required: true schema: type: string - name: page in: query description: The page to be fetched. required: false schema: type: integer format: int32 default: 0 - name: size in: query description: The page size to be fetched. Max value is 100. required: false schema: maximum: 100 type: integer format: int32 default: 10 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/ControlScenariosExecutionsPagedResponse' '400': description: Functional Error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '404': description: > Site not found A message is throwing with title UNKNOWN_SITE_EXCEPTION_ERROR if site-id is not valid content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' '500': description: Technical Error content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetail' components: schemas: ControlScenariosExecutionsPagedResponse: type: object properties: units: $ref: '#/components/schemas/ExecutionUnits' _embedded: type: object properties: executions: type: array items: $ref: '#/components/schemas/ControlScenariosExecutionsSite' _links: type: object properties: self: $ref: '#/components/schemas/Links' first: $ref: '#/components/schemas/Links' next: $ref: '#/components/schemas/Links' last: $ref: '#/components/schemas/Links' page: $ref: '#/components/schemas/PageMetadata' totalConsumptions: $ref: '#/components/schemas/ExecutionTotalConsumptions' ProblemDetail: required: - type - status properties: type: type: string title: type: string description: The problem title status: type: integer description: The problem status detail: type: string description: The problem detail instance: type: string description: The problem instance. By default, the request path properties: $ref: '#/components/schemas/Properties' description: Representation for an RFC 7807 problem detail ExecutionUnits: description: Units required: - energyMeter - cost - gain properties: energyMeter: type: string default: KWH cost: type: string default: EUR gain: type: string default: EUR ControlScenariosExecutionsSite: type: object properties: id: type: string description: Scenario Execution identifier example: 1abc62bb-1a39-4342-b6fd-2389a335b20a_01 scenarioId: type: string description: Scenario identifier example: DREEV_SMART_CHARGING type: type: string description: > Execution type. "RUN" means that the execution will RUN selected control scenario. "STOP" means that the execution will STOP selected control scenario. "CANCEL" means that the execution will CANCEL selected running control scenario. example: STOP enum: - RUN - STOP - CANCEL status: type: string description: > Global execution status. "REQUESTED" means that execution requests have been sent to each device provider. "OK" means that all requests succeed. "KO" means that all requests failed. "PARTIAL_KO" means some requests succeed and others failed. example: OK enum: - REQUESTED - OK - KO - PARTIAL_KO modificationTs: type: string description: Execution modification date, format ISO8601 (YYYY-MM-DDThh:mm:ssZ) example: '2024-12-31T23:00:00Z' trigger: $ref: '#/components/schemas/ControlScenariosExecutionTrigger' devicesExecutions: type: array items: $ref: '#/components/schemas/ControlScenariosDeviceExecution' consumption: $ref: '#/components/schemas/ExecutionConsumption' gain: $ref: '#/components/schemas/ExecutionGain' required: - id - scenarioId - type - status Links: type: object properties: href: type: string hreflang: type: string title: type: string type: type: string deprecation: type: string profile: type: string name: type: string templated: type: boolean PageMetadata: type: object properties: size: type: integer format: int64 totalElements: type: integer format: int64 totalPages: type: integer format: int64 number: type: integer format: int64 ExecutionTotalConsumptions: required: - energyMeter - cost properties: energyMeter: $ref: '#/components/schemas/ExecutionTotalConsumptionsEnergyMeter' cost: $ref: '#/components/schemas/ExecutionTotalConsumptionsCost' gain: $ref: '#/components/schemas/ExecutionTotalConsumptionsGain' Properties: type: object description: A generic map of properties ControlScenariosExecutionTrigger: type: object description: Trigger event object. properties: tariffOption: type: string description: Trigger tariff option. example: null value: type: string description: Trigger value. example: null type: type: string description: Trigger event type. example: null beginTs: type: string description: Trigger event begin date, format ISO8601 (YYYY-MM-DDThh:mm:ssZ) example: null endTs: type: string description: Trigger event end date, format ISO8601 (YYYY-MM-DDThh:mm:ssZ) example: null ControlScenariosDeviceExecution: type: object properties: id: type: string description: Device execution identifier example: 42fad7e9-9e14-40cd-8774-f35595afc0b7_01 deviceId: type: string description: Device identifier example: 5gth-40cd-8774-f35595afc0b7_01 status: type: string description: > Scenario device execution status. "REQUESTED" means that an execution request has been sent to the device provider. "OK" means that the request succeed. "KO" means that the request failed. enum: - OK - KO - REQUESTED ts: type: string description: device execution log date, format ISO8601 (YYYY-MM-DDThh:mm:ssZ) example: '2024-12-24 23:00:00+00:00' required: - id - status ExecutionConsumption: required: - period - energyMeter - cost properties: period: $ref: '#/components/schemas/ExecutionConsumptionPeriod' energyMeter: $ref: '#/components/schemas/ExecutionConsumptionEnergyMeter' cost: $ref: '#/components/schemas/ExecutionConsumptionCost' ExecutionGain: required: - total properties: total: type: number description: The value of gain example: 1.3 ExecutionTotalConsumptionsEnergyMeter: required: - total - smart - unoptimized - smartRatio properties: total: type: number description: The total energy consumption example: 10000 smart: type: number description: The energy consumption with optimization example: 8000 unoptimized: type: number description: The energy consumption without optimization example: 2000 smartRatio: type: number description: The proportion of smart consumption over total consumption example: 0.8 ExecutionTotalConsumptionsCost: required: - realCost properties: realCost: type: number description: The cost of all consumptions example: 50 fullUnoptimizedEstimatedCost: type: number description: The cost of all consumptions if they had not been optimized at all example: 76 ExecutionTotalConsumptionsGain: required: - total properties: total: type: number description: The gain of all executions due to smart energy management example: 26 ExecutionConsumptionPeriod: required: - startTime - endTime properties: startTime: type: string description: Consumption period begin date, format ISO8601 (YYYY-MM-DDThh:mm:ssZ) example: '2024-12-24T14:15:22Z' endTime: type: string description: Consumption period end date, format ISO8601 (YYYY-MM-DDThh:mm:ssZ) example: '2024-12-24T22:15:22Z' ExecutionConsumptionEnergyMeter: required: - total - unoptimized - smart - smartRatio properties: total: type: number description: The value of energy consumption example: 1000 unoptimized: type: number description: The energy consumption made without optimization example: 300 smart: type: number description: The energy consumption made with optimization example: 700 smartRatio: type: number description: The proportion of smart energy consumption over total consumption example: 0.7 ExecutionConsumptionCost: required: - realCost properties: realCost: type: number description: The value of consumption cost example: 3 fullUnoptimizedEstimatedCost: type: number description: >- The estimated cost of the transaction if it had not been optimized at all (i.e. without any smart consumption) example: 4.3 ````