# Check Status {% openapi src="" 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](https://developer.hyper3d.ai/api-specification/rodin-generation_reset_v). Once this API tell you that your task has finished, you can safely use the [Download API](https://developer.hyper3d.ai/api-specification/download-results_reset_v) 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](https://developer.hyper3d.ai/api-specification/download-results_reset_v) 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](https://developer.hyper3d.ai/api-specification/rodin-generation_reset_v). | ## 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 %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developer.hyper3d.ai/api-specification/check-status_reset_v.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.