Get Task Status

curl --request GET \
  --url https://api.hirebase.org/v2/tasks/{task_id}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hirebase.org/v2/tasks/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hirebase.org/v2/tasks/{task_id}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.hirebase.org/v2/tasks/{task_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "type": "<string>",
  "state": "<string>",
  "progress": 123,
  "created_at": "<string>",
  "updated_at": "<string>",
  "started_at": "<string>",
  "completed_at": "<string>",
  "user_id": "<string>",
  "error": "<string>",
  "error_code": "<string>",
  "retryable": true,
  "worker_id": "<string>",
  "priority": 123,
  "notify": true,
  "input": {
    "query": {},
    "format": "<string>"
  },
  "result": {
    "download_url": "<string>",
    "file_size": 123,
    "record_count": 123,
    "expiry_time": "<string>"
  }
}

GET

tasks

{task_id}

Get Task Status

curl --request GET \
  --url https://api.hirebase.org/v2/tasks/{task_id}

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hirebase.org/v2/tasks/{task_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hirebase.org/v2/tasks/{task_id}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.hirebase.org/v2/tasks/{task_id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "type": "<string>",
  "state": "<string>",
  "progress": 123,
  "created_at": "<string>",
  "updated_at": "<string>",
  "started_at": "<string>",
  "completed_at": "<string>",
  "user_id": "<string>",
  "error": "<string>",
  "error_code": "<string>",
  "retryable": true,
  "worker_id": "<string>",
  "priority": 123,
  "notify": true,
  "input": {
    "query": {},
    "format": "<string>"
  },
  "result": {
    "download_url": "<string>",
    "file_size": 123,
    "record_count": 123,
    "expiry_time": "<string>"
  }
}

Check the status, progress, and output of an asynchronous task by providing its unique task ID. Tasks may take anywhere from a few seconds to several hours to complete, depending on the size of the request. Task reads have their own rate limit of 600 requests per minute per key, separate from the 100 per minute shared by every other endpoint, so polling never slows down your searches and submits. To follow many tasks at once, use List Tasks.

Endpoint

GET  /v2/tasks/{task_id}

Path Parameters

string

required

The UUID of the task to query

Response

string

Unique identifier of the task

string

Type of the task. One of:

export_job_data — a job export. Paid historical exports use this type too, with input.collection set to "jobs_expired".
export_expired_jobs — an expired-jobs export.
contacts_extraction — hiring-contact research for a posting, from Hiring Manager Contacts.
enrich_contact — a work email and/or phone lookup for one contact, from Reveal Contact.
salary_benchmark — a posted-salary benchmark, from Salary Benchmark.

string

Current state of the task. The API returns these values lowercase:

queued — task accepted and waiting to be processed.
processing — task is currently being executed by a worker.
finished — task finished successfully; result is populated.
failed — task execution failed; see error, error_code and retryable.
canceled — the task was canceled before it finished.

number

Task progress as a float between 0.0 and 1.0

string

ISO timestamp of when the task was created

string

ISO timestamp of the last task update

string

ISO timestamp of when the task began processing

string

ISO timestamp of when the task finished processing

string

ID of the user who initiated the task

string

Error message if the task failed, otherwise null

string

Machine-readable failure reason if the task failed, otherwise null. For contacts tasks the values are listed under Why a task failed; every task type can also fail with temporary or internal.

boolean

If the task failed: true when submitting the same request again can succeed, false when it won’t. Otherwise null.

string

ID of the worker node that processed the task

integer

Priority level of the task (higher means more urgent)

boolean

Whether a completion email will be sent to the account address for this task (set via the notify parameter on the export request)

object

Parameters passed to the task

Show Example for Exporting Jobs

object

Search query used to filter jobs

string

Format for export (e.g., “json”, “csv”)

object

Output result from the task

Show Example Output for Exporting Jobs

string

Signed URL to download the result

integer

Size of the generated file in bytes

integer

Number of records in the exported file

string

ISO timestamp when the download URL will expire

Example Request

curl -X GET "https://api.hirebase.org/v2/tasks/YOUR_TASK_ID" \
  -H "x-api-key: YOUR_API_KEY"

Example Response

{
    "id": "8107c787-16b9-4763-af74-e2c789a5169n",
    "type": "export_job_data",
    "state": "finished",
    "progress": 1.0,
    "created_at": "2025-06-13T06:10:07.605000",
    "updated_at": "2025-06-13T06:10:08.647000",
    "started_at": "2025-06-13T06:10:07.723000",
    "completed_at": "2025-06-13T06:10:08.647000",
    "user_id": "68876d278da1b42f2878be12",
    "error": null,
    "worker_id": "worker-81ghedc2-4",
    "priority": 0,
    "input": {
        "query": {
            "job_titles": [
                "Site/Civil Engineer"
            ],
            "keywords": null,
            "location_group": null,
            "location_types": [
                "In-Person"
            ],
            "geo_locations": [
                {
                    "city": "Richmond",
                    "region": "Virginia",
                    "country": "United States"
                }
            ],
            "experience": null,
            "yoe": {
                "min": 1.0,
                "max": 6.0
            },
            "include_yoe": null,
            "company_types": null,
            "company_name": "companyxyz",
            "date_posted": null,
            "days_ago": null,
            "month": null,
            "salary": null,
            "include_no_salary": null,
            "currency": null,
            "job_types": [
                "Full Time"
            ],
            "job_category": null,
            "industry": [
                "Design",
                "Construction"
            ],
            "sub_industry": [
                "Architecture",
                "Building Construction"
            ],
            "visa": "false",
            "include_expired": null,
            "hide_seen_jobs": null,
            "user_id": null,
            "company_slug": null,
            "job_slug": null,
            "job_board": null,
            "sort_by": "relevance",
            "sort_order": "desc",
            "page": 1,
            "limit": 10
        },
        "format": "json"
    },
    "result": {
        "download_url": "https://sfo3.digitaloceanspaces.com/joby-uploads/user/32245d278da1b42f2878fa12/0ff6c9b7-138f-4c14-b0d6-95425b81d75d.json?AWSAccessKeyId=DO007W2A88HAEEP9W6VH&Signature=WP0LSTZZNKRoIukxxhzkiW%2Fh5uI%3D&Expires=1752387007",
        "file_size": 3455,
        "record_count": 10,
        "expiry_time": "2025-07-13T06:10:08.024758"
    }
}

Error Responses

401 Unauthorized

Returns when the API key is missing, invalid, or incorrect.

403 Forbidden

{"detail": "Not authorized to view this task"} — the task exists but belongs to a different account. Tasks are only visible to the API key that created them.

404 Not Found

Returns when the provided task_id is not valid.

500 Internal Server Error

Returns when an unexpected error occurs on the server.

Occurs during unhandled server-side failures or bugs that prevent the request from being processed.

Jobs API

Expired & Historical Jobs API

Hiring Manager API

Companies API

Insights API

Salary Benchmark API

Reference Data API

Resumes

Tasks API

Billing & Usage

Error Handling

Get Task Status

Endpoint

Path Parameters

Response

Example Request

Example Response

Error Responses

​Endpoint

​Path Parameters

​Response

​Example Request

​Example Response

​Error Responses

Endpoint

Path Parameters

Response

Example Request

Example Response

Error Responses