> For the complete documentation index, see [llms.txt](https://developer.hyper3d.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.hyper3d.ai/api-specification/check-status_reset_v.md).

# Check Status

{% openapi src="/files/Je9OFYyZQsIgvfgeSmOD" path="/api/v2/status" method="post" %}
[Cancel.yaml](https://3170127470-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fve7H9sNOF32Exg6OAhKo%2Fuploads%2Fgit-blob-e76a8dee23c33ddbc4b1828853a02009f4d90acf%2FCancel.yaml?alt=media)
{% endopenapi %}

The Generation APIs are time and resource consuming, so we designed them to be asynchronous. This means that you submit a task without getting the result immediately.

{% hint style="warning" %}
Please refrain from calling this API too frequently as it may incur some addtional stress to our servers. We may throttle some requests that are sent too frequently.
{% endhint %}

Instead, your program can then periodically check the status of the task you submitted by supplying the API endpoint the task subscription key you got from your [Generation API call](/api-specification/rodin-generation_reset_v.md). Once this API tell you that your task has finished, you can safely use the [Download API](/api-specification/download-results_reset_v.md) to get a list of URLs from where you can download the result models of your task submitted.

The following table lists the possible values from the API call in the `status` field and the semantics of them.

| Status       | Meaning                                                                                                                                    |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `Waiting`    | Your task has entered our task queue waiting to be scheduled for execution.                                                                |
| `Generating` | Our worker is working on generating models for your task.                                                                                  |
| `Done`       | The task is done. In this case, you can head to the [Download API](/api-specification/download-results_reset_v.md) to download the result. |
| `Failed`     | The task has failed during execution. In this case, you may need to contact our support for details.                                       |

## Pricing

We do not charge any addtional credits for calling this API to check the status of your task.

## Request

### Authentication

This API uses bearer key for authentication. You need to include a valid token in the `Authorization` header for all requests.

```
Authorization: Bearer RODIN_API_KEY
```

### **Body**

The API takes one parameter in the `POST` request body.

| Parameter             | Type       | Description                                                                                                                                                                                          |
| --------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **subscription\_key** | **string** | **Required.** The subscription key of the task you want to query the status of. Typically you will get it in the response from the [Generation API](/api-specification/rodin-generation_reset_v.md). |

## Response

The JSON response has the following fields.

| Property    | Type             | Description                                                                                             |
| ----------- | ---------------- | ------------------------------------------------------------------------------------------------------- |
| error       | string           | Optional. Error message, if any.                                                                        |
| jobs        | array of objects | The jobs of the task, containing details of individual jobs executed as part of the generation process. |
| jobs.uuid   | string           | The uuid of the job.                                                                                    |
| jobs.status | string           | The status of the job. The possible values are summarized [in the table above.](#api-v2-status)         |

## **Examples**

{% tabs %}
{% tab title="Request with cURL" %}

```sh
export RODIN_API_KEY="your api key"
curl -X 'POST' \
  'https://api.hyper3d.com/api/v2/status' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "subscription_key": "your-subscription-key"
}'
unset RODIN_API_KEY
```

{% endtab %}

{% tab title="Request with Python 3" %}

```python
import requests
import os

ENDPOINT = "https://api.hyper3d.com/api/v2/status"
API_KEY = os.getenv("HYPER3D_API_KEY")
SUBSCRIPTION_KEY = "your-subscription-key"  # Replace with your actual subscription key

# Prepare the headers
headers = {
    'accept': 'application/json',
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {API_KEY}',
}

# Prepare the JSON payload
data = {
    "subscription_key": SUBSCRIPTION_KEY
}

# Make the POST request
response = requests.post(ENDPOINT, headers=headers, json=data)

# Parse and return the JSON response
print(response.json())

```

{% endtab %}

{% tab title="Request with Go" %}

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
)

const BaseURI = "https://api.hyper3d.com/api"

type CommonError struct {
	Error *string `json:"error,omitempty"`
}

type ApiTaskStatusPair struct {
	Uuid   string `json:"uuid"`
	Status string `json:"status"`
}

type ApiStatusResponse struct {
	CommonError
	Jobs []ApiTaskStatusPair `json:"jobs"`
}

func CheckStatus(token string, subscriptionKey string) (*ApiStatusResponse, error) {
	payload := map[string]string{"subscription_key": subscriptionKey}

	jsonData, err := json.Marshal(payload)
	if err != nil {
		return nil, err
	}

	req, err := http.NewRequest("POST", fmt.Sprintf("%s/v2/status", BaseURI), bytes.NewBuffer(jsonData))
	if err != nil {
		return nil, err
	}

	req.Header.Set("Authorization", "Bearer "+token)
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	var responseData ApiStatusResponse
	err = json.NewDecoder(resp.Body).Decode(&responseData)
	if err != nil {
		return nil, err
	}

	if responseData.Error != nil {
		return nil, fmt.Errorf("error: %s", *responseData.Error)
	}

	return &responseData, nil
}

func main() {
	// Replace with your actual API key
	token := "your api key"
	// Replace with your subscription key
	resp, _ := CheckStatus(token, "your subscription key for a task")
	fmt.Println(resp)
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
  "jobs": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "status": "Generating"
    }
  ]
}
```

{% endtab %}
{% endtabs %}