## Overview Run advanced processing on tasking and catalog data in your storage. Get access Find data Run a job Monitor and download Ensure you have access to the desired process. [Go to step](https://docs.up42.com#access) Find the data you want to process. [Go to step](https://docs.up42.com#data) Configure job parameters and run it. [Go to step](https://docs.up42.com#creation) Monitor the job's status and download the delivered assets from storage. [Go to step](https://docs.up42.com#download) 1 ## Get access Users with the Viewer [role](https://docs.up42.com/getting-started/roles) don’t have the permissions to complete this step. 1. **Select a process** [Review the specifications](https://docs.up42.com/processing/processes) of processes and select a process you want to run. Processes can be divided into two categories: - [Enhancement](https://docs.up42.com/processing/processes?processType=Enhancement) processes that preprocess imagery to improve its visual quality. - [Analytics](https://docs.up42.com/processing/processes?processType=Analytics) processes that extract insights from imagery. To get a list of all processes, call the [Get processes](https://developer.up42.com/reference/processinggetprocesses?utm_source=documentation) endpoint. Select the process you want to proceed with and retrieve its name ID. 2. **Accept the EULA** If you want to run the chosen process for the first time, [review and accept its end-user license agreement (EULA)](https://docs.up42.com/developers/api-eulas). If a EULA is updated, you need to re-accept it before creating your next job. 2 ## Find data Search for data in one of the following ways: - Using a [simple search](https://docs.up42.com/developers/api-stac#simple-search), if you already know which item you want to use. - Using a [detailed search](https://docs.up42.com/developers/api-stac#detailed-search), if you want to find a compatible item. You can only process items that come from a [supported collection](https://docs.up42.com/data-management/collections) and that are added to storage starting in 2023. 3 ## Run a job Users with the Viewer [role](https://docs.up42.com/getting-started/roles) don’t have the permissions to complete this step. 1. **Prepare your request** Call the [Get a process](https://developer.up42.com/reference/processinggetprocess?utm_source=documentation) endpoint with the process name ID as the path parameter and check the `inputs` object for required and optional input parameters. Prepare your request body by following the structure specified in the corresponding process. How to read processing schemas For example, this is [Coregistration](https://docs.up42.com/processing/coregistration-simularity)’s schema: ```json { "id": "coregistration-simularity", "title": "Coregistration", "description": "An algorithm that improves the positional accuracy of imagery against a reference.", <...> "inputs": { "title": { "title": "Title", "description": "The title of the produced STAC objects.", "minOccurs": 1, "maxOccurs": 1, "schema": { "type": "string", "minLength": 1, "maxLength": 250 } }, "sourceItem": { "title": "Source STAC item", "description": "A unique identifier of the source item to be coregistered.", "minOccurs": 1, "maxOccurs": 1, "schema": { "type": "string", "format": "uri", "description": "The path to a STAC item in the '/v2/assets/stac/collections/{collection-id}/items/{item-id}' format." } }, "referenceItem": { "title": "Reference STAC item", "description": "A unique identifier of the reference item.", "minOccurs": 1, "maxOccurs": 1, "schema": { "type": "string", "format": "uri", "description": "The path to a STAC item in the '/v2/assets/stac/collections/{collection-id}/items/{item-id}' format." } } <...> } } ``` The parameters in the `inputs` object need to be specified. For the `coregistration-simularity` process, these are the following parameters: - Title - Source item - Reference item A sample request body for this process: ```json { "inputs": { "title": "Coregistering imagery over Berlin", "sourceItem": "https://api.up42.com/v2/assets/stac/collections/<...>/items/<...>", "referenceItem": "https://api.up42.com/v2/assets/stac/collections/<...>/items/<...>" } } ``` 2. **Validate your input** To check the validity of your input, call the [Validate input for a process](https://developer.up42.com/reference/processingvalidate?utm_source=documentation) endpoint with the [name ID](https://docs.up42.com/developers/api-processing#job-run) of the selected process as the path parameter. For the request body, use the prepared JSON. If a job has been validated, there will be a **HTTP 200 OK** response with no body. In case of any errors in the input, the returned error message will point to what caused it: ```json { "errors": [ { "name": "MissingPanchromaticAsset", "message": "The panchromatic band is missing." } ] } ``` 3. **Determine the cost** To check the cost of a processing job before creating it, call the [Determine the cost of a process](https://developer.up42.com/reference/processingevaluate?utm_source=documentation) endpoint with the [name ID](https://docs.up42.com/developers/api-processing#job-run) of the selected process as the path parameter and the following parameters in the request body: - A custom title - The [STAC item](https://docs.up42.com/developers/api-stac#items) you want to apply the algorithm to ```json { "inputs": { "title": "Pansharpened imagery over UK", "item": "https://api.up42.com/v2/assets/stac/collections/21c0b14e-3434-4675-98d1-f225507ded99/items/23e4567-e89b-12d3-a456-426614174000" } } ``` You’ll receive an overview of the overall UP42 credit amount that will be deducted from your credit balance if you decide to run the selected process: ```json { "pricingStrategy": "area", "totalCredits": 63, // The process cost, in credits "totalSize": 15.8, "unit": "SQ_KM" } ``` 4. **Run a new processing job** This action can’t be done with the Viewer [role](https://docs.up42.com/getting-started/roles). Credits will be deducted upon successful completion of the created processing job. The transaction can’t be reversed. To create a job, call the [Run a process](https://developer.up42.com/reference/processingexecute?utm_source=documentation) endpoint with the following parameters: - The [name ID](https://docs.up42.com/developers/api-processing#job-run) of the selected process as the path parameter - Your workspace ID as the query `workspaceId` parameter ```http POST /v2/processing/processes//execution?workspaceId= HTTP/1.1 Host: api.up42.com Authorization: Bearer {token} ``` ```shell curl --location 'https://api.up42.com/v2/processing/processes//execution?workspaceId=' \ --header 'Authorization: Bearer {token} ``` For the request body, use the prepared JSON. 4 ## Monitor and download 1. **Check job status** Get processing jobs as follows: - Retrieve information about all jobs by calling the [Get processing jobs](https://developer.up42.com/reference/processinggetjobs?utm_source=documentation) endpoint. - Retrieve information about a specific job by calling the [Get a processing job](https://developer.up42.com/reference/processinggetjob?utm_source=documentation) with the job ID as the path parameter. The most useful parameter for monitoring is job status. Job statuses [Job statuses ](https://docs.up42.com#job-statuses "Copy link to this section") | API status | Description | Console status | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | | `created` | The job has been created, but not yet accepted. | **In progress** | | `licensed` | The EULA has been accepted for this process. The job will move on to the validation stage. | **In progress** | | `unlicensed` | The EULA hasn’t been accepted for this process. The job will fail. [Accept the EULA](https://docs.up42.com/developers/api-eulas) and try again. | **Unlicensed** | | `valid` | The job has been validated. | **In progress** | | `accepted` | The job has been validated and accepted. The credits corresponding to the price are temporarily withheld until the job is completed. | **In progress** | | `invalid` | The job has failed validation. Fix your input parameters and try again. | **Not valid** | | `rejected` | The job has been canceled due to an insufficient account balance. Top up your balance and try again. | **Rejected** | | `running` | The job is in progress. | **In progress** | | `successful` | The job has been completed, and the results have been delivered to your storage. | **Completed** | | `captured` | The job has been completed, the results have been delivered to your storage, and any withheld credits have been deducted from your account balance. | **Completed** | | `released` | The job has failed. Any withheld credits have been released. Try again, and if the issue persists, contact support. | **Failed** | | `failed` | The job has failed. | **Failed** | The following job statuses mean you can download processing results from storage: - `successful` - `captured` 2. **Retrieve assets’ links** To get all assets from a specific job, call the [Get specific STAC items](https://developer.up42.com/reference/postsassearch?utm_source=documentation) endpoint with the following [request body](https://docs.up42.com/developers/api-stac#detailed-search), using your job ID: ```json { "filter": { "args": [ { "property": "job_id" }, "68567134-27ad-7bd7-4b65-d61adb11fc78" // Replace with your job ID ], "op": "=" } } ``` The response will contain your job results listed in the `features.assets` object. Retrieve the IDs of the assets you want to access. ```json { "links": [], // Additional links "type": "FeatureCollection", "features": [ { "assets": { "072e661d_pan_68567134-27ad-7bd7-4b65-d61adb11fc78.tiff": { "href": "https://api.up42.com/v2/assets/ea36dee9-fed6-457e-8400-2c20ebd30f44", // The asset ID in this example is ea36dee9-fed6-457e-8400-2c20ebd30f44 "title": "Pansharpened multispectral data", "type": "image/tiff; application=geotiff; profile=cloud-optimized", "roles": ["pansharpened", "data", "multispectral"] } }, // Other parameters "type": "Feature", "stac_version": "1.0.0" } ] } ``` You can generate a pre-signed URL to download an asset without authentication by calling the [Create a download URL](https://developer.up42.com/reference/generatedownloadurlexternal?utm_source=documentation) endpoint with the asset ID as the path parameter. The generated URL is valid for 5 minutes and can be shared. The URL will have the following format: ```json { "url": "https://storage.googleapis.com/user-storage-interstellar-prod/assets/<...>" } ```