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

# Status

> Check operation and per-file status via the Business API.

The status endpoints let you track the lifecycle of operations created via `/api/v1/do`.

* `GET /api/v1/status/:mainTaskId`
* `GET /api/v1/status/:mainTaskId/:fileKey`

These routes are backed by the `OperationStatusFileData`, and `OperationStatusResponse` types.

## Status schema

```ts theme={null}
type OperationStatusFileData = {
  file_key: string; // resulting file key (output if available, otherwise input)
  status: "QUEUED" | "IN_PROGRESS" | "COMPLETED" | "FAILED";
  download_link?: string; // relative path to download the output file
  error_code?: string; // optional short failure code
  error_message?: string; // optional human-readable message
};

type OperationStatusResponse = {
  operation_status: "QUEUED" | "IN_PROGRESS" | "COMPLETED" | "FAILED";
  files_data?: OperationStatusFileData[];
};
```

## Get main task status

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.dragdropdo.com/api/v1/status/main_task_abc123 \
    -H "Authorization: Bearer your-api-key"
  ```

  ```ts NODE theme={null}
  import { Dragdropdo } from "dragdropdo-sdk";

  const client = new Dragdropdo({
    apiKey: "your-api-key",
    baseURL: "https://api.dragdropdo.com",
  });

  // Get status
  const status = await client.getStatus({
    mainTaskId: "task_abc123",
  });

  console.log("Operation status:", status.operationStatus);
  if (status.operationStatus === "completed") {
    status.filesData?.forEach((file) => {
      console.log(`File ${file.fileKey}: ${file.downloadLink}`);
    });
  }
  ```

  ```python PYTHON theme={null}
  from dragdropdo_sdk import Dragdropdo, D3ClientConfig

  client = Dragdropdo(
      api_key="your-api-key",
      base_url="https://api.dragdropdo.com"
  )

  # Get status
  status = client.get_status(main_task_id="task_abc123")

  print("Operation status:", status.operation_status)
  if status.operation_status == "completed":
      for file in status.files_data:
          print(f"File {file.file_key}: {file.download_link}")
  ```

  ```php PHP theme={null}
  use DragdropdoSdk\Dragdropdo;

  $client = new Dragdropdo([
      'api_key' => 'your-api-key',
      'base_url' => 'https://api.dragdropdo.com',
  ]);

  // Get status
  $status = $client->getStatus(['main_task_id' => 'task_abc123']);

  echo "Operation status: " . $status['operation_status'] . "\n";
  if ($status['operation_status'] === 'completed') {
      foreach ($status['files_data'] as $file) {
          echo "File {$file['file_key']}: {$file['download_link']}\n";
      }
  }
  ```

  ```ruby RUBY theme={null}
  require 'dragdropdo_sdk'

  client = DragdropdoSdk::Dragdropdo.new(
    api_key: 'your-api-key',
    base_url: 'https://api.dragdropdo.com'
  )

  # Get status
  status = client.get_status(main_task_id: 'task_abc123')

  puts "Operation status: #{status[:operation_status]}"
  if status[:operation_status] == 'completed'
    status[:files_data].each do |file|
      puts "File #{file[:file_key]}: #{file[:download_link]}"
    end
  end
  ```

  ```go GO theme={null}
  import "github.com/d3/dragdropdo-sdk-go"

  client, _ := d3.NewDragdropdo(d3.Config{
      APIKey:  "your-api-key",
      BaseURL: "https://api.dragdropdo.com",
  });

  // Get status
  status, _ := client.GetStatus(d3.StatusOptions{
      MainTaskID: "task_abc123",
  });

  fmt.Printf("Operation status: %s\n", status.OperationStatus)
  if status.OperationStatus == "completed" {
      for _, file := range status.FilesData {
          fmt.Printf("File %s: %s\n", file.FileKey, file.DownloadLink)
      }
  }
  ```

  ```java JAVA theme={null}
  import com.dragdropdo.sdk.Dragdropdo;
  import com.dragdropdo.sdk.DragdropdoConfig;
  import com.dragdropdo.sdk.models.*;

  Dragdropdo client = new Dragdropdo(
      new DragdropdoConfig("your-api-key")
          .setBaseUrl("https://api.dragdropdo.com")
  );

  // Get status
  StatusResponse status = client.getStatus(
      new StatusOptions().setMainTaskId("task_abc123")
  );

  System.out.println("Operation status: " + status.getOperationStatus());
  if ("completed".equals(status.getOperationStatus())) {
      status.getFilesData().forEach(file ->
          System.out.println("File " + file.getFileKey() + ": " + file.getDownloadLink())
      );
  }
  ```
</CodeGroup>

**Response (completed):**

```json theme={null}
{
  "operation_status": "completed",
  "files_data": [
    {
      "file_key": "file_key_1_result",
      "status": "completed",
      "download_link": "https://api.dragdropdo.com/v1/download/file_key_1_result"
    },
    {
      "file_key": "file_key_2_result",
      "status": "completed",
      "download_link": "https://api.dragdropdo.com/v1/download/file_key_2_result"
    }
  ]
}
```

**Response (failed):**

```json theme={null}
{
  "operation_status": "failed",
  "files_data": [
    {
      "file_key": "file_key_1",
      "status": "failed",
      "error_code": "internal_error",
      "error_message": "Internal server error / invalid input file"
    }
  ]
}
```

## Get specific file task status

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.dragdropdo.com/api/v1/status/task_abc123/file_key_123 \
    -H "Authorization: Bearer your-api-key"
  ```

  ```ts NODE theme={null}
  import { Dragdropdo } from "dragdropdo-sdk";

  const client = new Dragdropdo({
    apiKey: "your-api-key",
    baseURL: "https://api.dragdropdo.com",
  });

  // Get specific file status by file key
  const status = await client.getStatus({
    mainTaskId: "task_abc123",
    fileKey: "file_key_123",
  });

  console.log("File status:", status.filesData?.[0]?.status);
  ```

  ```python PYTHON theme={null}
  from dragdropdo_sdk import Dragdropdo, D3ClientConfig

  client = Dragdropdo(
      api_key="your-api-key",
      base_url="https://api.dragdropdo.com"
  )

  # Get specific file status by file key
  status = client.get_status(
      main_task_id="task_abc123",
      file_key="file_key_123"
  )

  print("File status:", status.files_data[0].status if status.files_data else None)
  ```

  ```php PHP theme={null}
  use DragdropdoSdk\Dragdropdo;

  $client = new Dragdropdo([
      'api_key' => 'your-api-key',
      'base_url' => 'https://api.dragdropdo.com',
  ]);

  // Get specific file status by file key
  $status = $client->getStatus([
      'main_task_id' => 'task_abc123',
      'file_key' => 'file_key_123',
  ]);

  echo "File status: " . ($status['files_data'][0]['status'] ?? 'N/A') . "\n";
  ```

  ```ruby RUBY theme={null}
  require 'dragdropdo_sdk'

  client = DragdropdoSdk::Dragdropdo.new(
    api_key: 'your-api-key',
    base_url: 'https://api.dragdropdo.com'
  )

  # Get specific file status by file key
  status = client.get_status(
    main_task_id: 'task_abc123',
    file_key: 'file_key_123'
  )

  puts "File status: #{status[:files_data]&.first&.dig(:status)}"
  ```

  ```go GO theme={null}
  import "github.com/d3/dragdropdo-sdk-go"

  client, _ := d3.NewDragdropdo(d3.Config{
      APIKey:  "your-api-key",
      BaseURL: "https://api.dragdropdo.com",
  });

  // Get specific file status by file key
  status, _ := client.GetStatus(d3.StatusOptions{
      MainTaskID: "task_abc123",
      FileKey:    "file_key_123",
  });

  if len(status.FilesData) > 0 {
      fmt.Printf("File status: %s\n", status.FilesData[0].Status)
  }
  ```

  ```java JAVA theme={null}
  import com.dragdropdo.sdk.Dragdropdo;
  import com.dragdropdo.sdk.DragdropdoConfig;
  import com.dragdropdo.sdk.models.*;

  Dragdropdo client = new Dragdropdo(
      new DragdropdoConfig("your-api-key")
          .setBaseUrl("https://api.dragdropdo.com")
  );

  // Get specific file status by file key
  StatusResponse status = client.getStatus(
      new StatusOptions()
          .setMainTaskId("task_abc123")
          .setFileKey("file_key_123")
  );

  if (!status.getFilesData().isEmpty()) {
      System.out.println("File status: " + status.getFilesData().get(0).getStatus());
  }
  ```
</CodeGroup>

When `fileKey` is present, the response narrows to the matching file task (if found).

## Polling vs. webhooks

* **Polling** – use the status endpoints from your backend or via the official SDK (see **SDKs → Node**).
* **Webhooks** – for production workloads, configure webhooks to receive `operation.completed`, `operation.failed`, `fileTask.completed`, and `fileTask.failed` events instead of (or in addition to) polling.

### Polling example

<CodeGroup>
  ```bash cURL theme={null}
  # Poll in a loop (bash example)
  while true; do
    response=$(curl -s -X GET https://api.dragdropdo.com/api/v1/status/task_abc123 \
      -H "Authorization: Bearer your-api-key")
    
    status=$(echo $response | jq -r '.operation_status')
    echo "Status: $status"
    
    if [ "$status" = "completed" ] || [ "$status" = "failed" ]; then
      echo $response | jq '.'
      break
    fi
    
    sleep 2
  done
  ```

  ```ts NODE theme={null}
  import { Dragdropdo } from "dragdropdo-sdk";

  const client = new Dragdropdo({
    apiKey: "your-api-key",
    baseURL: "https://api.dragdropdo.com",
  });

  // Poll until completion
  const status = await client.pollStatus({
    mainTaskId: "task_abc123",
    interval: 2000, // Check every 2 seconds
    timeout: 300000, // 5 minutes max
    onUpdate: (status) => {
      console.log("Status:", status.operationStatus);
    },
  });

  if (status.operationStatus === "completed") {
    console.log("Operation completed!");
    status.filesData?.forEach((file) => {
      console.log(`Download: ${file.downloadLink}`);
    });
  }
  ```

  ```python PYTHON theme={null}
  from dragdropdo_sdk import Dragdropdo, D3ClientConfig

  client = Dragdropdo(
      api_key="your-api-key",
      base_url="https://api.dragdropdo.com"
  )

  # Poll until completion
  status = client.poll_status(
      main_task_id="task_abc123",
      interval=2000,  # Check every 2 seconds
      timeout=300000,  # 5 minutes max
      on_update=lambda s: print(f"Status: {s.operation_status}")
  )

  if status.operation_status == "completed":
      print("Operation completed!")
      for file in status.files_data:
          print(f"Download: {file.download_link}")
  ```

  ```php PHP theme={null}
  use DragdropdoSdk\Dragdropdo;

  $client = new Dragdropdo([
      'api_key' => 'your-api-key',
      'base_url' => 'https://api.dragdropdo.com',
  ]);

  // Poll until completion
  $status = $client->pollStatus([
      'main_task_id' => 'task_abc123',
      'interval' => 2000, // Check every 2 seconds
      'timeout' => 300000, // 5 minutes max
      'on_update' => function($status) {
          echo "Status: " . $status['operation_status'] . "\n";
      },
  ]);

  if ($status['operation_status'] === 'completed') {
      echo "Operation completed!\n";
      foreach ($status['files_data'] as $file) {
          echo "Download: " . $file['download_link'] . "\n";
      }
  }
  ```

  ```ruby RUBY theme={null}
  require 'dragdropdo_sdk'

  client = DragdropdoSdk::Dragdropdo.new(
    api_key: 'your-api-key',
    base_url: 'https://api.dragdropdo.com'
  )

  # Poll until completion
  status = client.poll_status(
    main_task_id: 'task_abc123',
    interval: 2000, # Check every 2 seconds
    timeout: 300000, # 5 minutes max
    on_update: ->(s) { puts "Status: #{s[:operation_status]}" }
  )

  if status[:operation_status] == 'completed'
    puts "Operation completed!"
    status[:files_data].each do |file|
      puts "Download: #{file[:download_link]}"
    end
  end
  ```

  ```go GO theme={null}
  import "github.com/d3/dragdropdo-sdk-go"
  import "time"

  client, _ := d3.NewDragdropdo(d3.Config{
      APIKey:  "your-api-key",
      BaseURL: "https://api.dragdropdo.com",
  });

  // Poll until completion
  status, _ := client.PollStatus(d3.PollStatusOptions{
      StatusOptions: d3.StatusOptions{
          MainTaskID: "task_abc123",
      },
      Interval: 2 * time.Second, // Check every 2 seconds
      Timeout:  5 * time.Minute, // 5 minutes max
      OnUpdate: func(s d3.StatusResponse) {
          fmt.Printf("Status: %s\n", s.OperationStatus)
      },
  });

  if status.OperationStatus == "completed" {
      fmt.Println("Operation completed!")
      for _, file := range status.FilesData {
          fmt.Printf("Download: %s\n", file.DownloadLink)
      }
  }
  ```

  ```java JAVA theme={null}
  import com.dragdropdo.sdk.Dragdropdo;
  import com.dragdropdo.sdk.DragdropdoConfig;
  import com.dragdropdo.sdk.models.*;

  Dragdropdo client = new Dragdropdo(
      new DragdropdoConfig("your-api-key")
          .setBaseUrl("https://api.dragdropdo.com")
  );

  // Poll until completion
  StatusResponse status = client.pollStatus(
      new PollStatusOptions()
          .setMainTaskId("task_abc123")
          .setInterval(2000) // Check every 2 seconds
          .setTimeout(300000) // 5 minutes max
          .setOnUpdate(s -> System.out.println("Status: " + s.getOperationStatus()))
  );

  if ("completed".equals(status.getOperationStatus())) {
      System.out.println("Operation completed!");
      status.getFilesData().forEach(file ->
          System.out.println("Download: " + file.getDownloadLink())
      );
  }
  ```
</CodeGroup>

See **Business API → Webhooks** for event payload shapes.