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

# Introduction to our Calculation engine

> An intro on how to use our Calculation engine and its background job system

## Long running tasks

Our Calculation module consists of several functionalities, going from projecting estimated costs of renovations to the automated scanning of energy performance certificates and extracting structured information out of them. As these tasks contain lots of business logic written in lots of lines of code, they naturally fit better in an asynchronous processing system. The entity that acts as a central entry point to this system, is the Calculation Job.

## Lifecycle of a Calculation Job

A Calculation Job can be created by the client via multiple endpoints, each of which has the responsibility to create a job of exactly one type. For example, to start a new suggested renovation trajectory calculation, a Calculation Job with type `SUGGESTED_RENOVATION_TRAJECTORY_CALCULATION` can be created using [this specific endpoint](/api-reference/calculation/suggested-renovation-trajectory-calculation). The endpoints and their references will clearly define all of the input parameters that need to be provided when using them.

After a Calculation Job has been made, it will usually start running within a few moments. This depends however on the current load of the system, the resources available and the specific configuration for the Calculation Job type at hand. When this happens, the `calculation_job_status` field will transition from `NOT_STARTED` to `RUNNING`.

When the Calculation Job has finished its run, it can either be in a `FAILED` or `FINISHED` state. If everything went well, `FINISHED` will therefore indicate the job has ended and, in case of relevance, results can be found in the `metadata` property of the Calculation Job.

## Fetching Calculation Job details

As outlined above, Calculation Jobs might take some time before being finished. A client therefore has to poll the system in order to know its latest status and metadata including its results. [This endpoint](/api-reference/calculation/get-calculation-job) acts as the main way to do this.

<Tip>You'll need an ID of the Calculation Job when calling the endpoint to fetch its details. This ID will be returned when creating the Calculation Job via the API in the first step.</Tip>
