codegreen.queries

codegreen.queries.get_data(submission_type, dump=False, experiment_name=None)

Retrieve the data submitted to the server. There are currently three options: the codecarbon logs, the nextflow logs and the request log for all the requests made to the server.

Parameters:

  • submission_type (str) – One of [‘codecarbon’, ‘nextflow’, ‘requests’]

  • dump (bool, optional) – Dump all data, can only be used in combination with an admin API key, defaults to False

  • experiment_name (str, optional) – Name of the experiment to identify the configuration file by., defaults to None

Raises:

UnauthorizedException – raised when no valid API key is submitted.

Returns:

Returns the data as a Dataframe

Return type:

pd.DataFrame

codegreen.queries.get_location_prediction(estimated_runtime_hours=1, estimated_run_time_in_minutes=12, percent_renewable=40, hard_finish_time=1742252400.116934, area_code=['DE', 'FR'], log_request=True, process_id=None, experiment_name=None)

Get a preddiction for the optimal location to perform the computation within the given time frame using the specified percentage of renewable energy.

Parameters:

  • estimated_runtime_hours (int, optional) – Run time of the code in hours, defaults to 1

  • estimated_run_time_in_minutes (int, optional) – additional run time of the code in minutes, defaults to 12

  • percent_renewable (int, optional) – required percentage of renewable energy in the grid at the time of computation, defaults to 40

  • hard_finish_time (datetime.timestamp, optional) – Deadline for the termination of the code, defaults to datetime.utcnow().replace(hour=24, minute=0, second=0).timestamp() which is 24 ahead.

  • area_code (list[str], optional) – list of potential area codes for the computation, defaults to [‘DE’,’FR’]

  • log_request (bool, optional) – allow logging the request at the server side, defaults to True

  • process_id (str, optional) – process id to scope the project, defaults to None

  • experiment_name (str, optional) – Name of the experiment to load the correct configuration, defaults to None

Raises:

UnauthorizedException – Raised if no correct API key is submitted with the request.

Returns:

A response in for the request with the content in json format.

Return type:

requests.Response

codegreen.queries.get_prediction(estimated_runtime_hours=1, estimated_run_time_in_minutes=0, hard_finish_time=datetime.datetime(2025, 3, 18, 19, 59, 57, 116920), log_request=True, process_id=None, experiment_name=None)

Get a prediction for an optimal time given the specified parameters. :param estimated_runtime_hours: Estimated run time in hours, defaults to 1 :type estimated_runtime_hours: int, optional :param estimated_run_time_in_minutes: Estimated additional minutes of runtime, defaults to 12 :type estimated_run_time_in_minutes: int, optional :param hard_finish_time: deadline for when the computation needs to be finished, defaults to 24 hours from the current time :type hard_finish_time: datetime.timestamp, optional :param log_request: allow logging the request server side, this is required to compute the carbon offset, defaults to True :type log_request: bool, optional :param process_id: An string to identify the experiment, defaults to None :type process_id: str, optional :param experiment_name: Name of the experiment used to load the configuration. If none it will try to load a default configuration, defaults to None :type experiment_name: str, optional :raises UnauthorizedException: raised when the API key is invalid :return: A response object representing the the prediction in the form of a json object, Example: {‘optimal_start’: 1689703307, ‘message’: ‘No data available’, ‘avg_percentage_renewable’: 0} :rtype: requests.Response

Parameters:

  • estimated_runtime_hours (int)

  • estimated_run_time_in_minutes (int)

  • hard_finish_time (timestamp)

  • log_request (bool)

  • process_id (str)

  • experiment_name (str)

Return type:

Response

codegreen.queries.submit_cc_resource_usage(trace_file, process_id, task_name, postal_code='DE-791', experiment_name=None)

Upload the codecarbon report in the file specified. Process id needs to be provided. The experiment name can be used to use a specific experiment configuration. Otherwise the experiment will be reported under the default settings.

Parameters:

  • trace_file (str) – Name of the nextflow trace file to upload.

  • process_id (str) – The process id to upload the nextflow report under. Can be used for scoped reporting within an API key scope.

  • task_name (str) – The name of the task to upload the nextflow report under

  • experiment_name (str, optional) – Name of the experiment to report under, defaults to None

  • postal_code (str) – Can be used to obfuscate the exact location.

Raises:

UnauthorizedException – will be raised if the API key is invalid or does not exist.

Returns:

The response of the server.

Return type:

requests.Response

codegreen.queries.submit_nf_resource_usage(trace_file, process_id, experiment_name=None)

Upload the nextflow report in the trace file. Process id needs to be provided. The experiment name can be used to use a specific experiment configuration. Otherwise the experiment will be reported under the default settings.

Parameters:

  • trace_file (str) – Name of the nextflow trace file to upload.

  • process_id (str) – The process id to upload the nextflow report under. Can be used for scoped reporting within an API key scope.

  • experiment_name (str, optional) – Name of the experiment to report under, defaults to None

Raises:

UnauthorizedException – will be raised if the API key is invalid or does not exist.

Returns:

The response of the server.

Return type:

requests.Response