Skip to main content
GET
/
v1
/
tasks
/
{task_id}
Get task status and results
curl --request GET \
  --url https://api.socq.ai/v1/tasks/{task_id} \
  --header 'Authorization: Bearer <token>'
import requests

url = "https://api.socq.ai/v1/tasks/{task_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.socq.ai/v1/tasks/{task_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.socq.ai/v1/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",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);

$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.socq.ai/v1/tasks/{task_id}"

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

req.Header.Add("Authorization", "Bearer <token>")

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

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

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.socq.ai/v1/tasks/{task_id}")
.header("Authorization", "Bearer <token>")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.socq.ai/v1/tasks/{task_id}")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
{
  "code": 200,
  "data": {
    "task_id": "<string>",
    "result_count": 123,
    "error_message": "<string>",
    "credits_amount": 123,
    "created_time": "2023-11-07T05:31:56Z",
    "finished_time": "2023-11-07T05:31:56Z",
    "results": {
      "limit": 50,
      "has_more": true,
      "items": [
        {
          "id": "<string>",
          "platform": "<string>",
          "resource": "<string>",
          "type": "<string>",
          "url": "<string>",
          "metrics": {},
          "media": [
            {}
          ],
          "created_at": "2023-11-07T05:31:56Z",
          "collected_at": "2023-11-07T05:31:56Z",
          "extra": {}
        }
      ],
      "next_cursor": "NTY3ODkw"
    }
  }
}
{
"code": 123,
"error": {
"message": "<string>",
"type": "<string>"
}
}
{
"code": 123,
"error": {
"message": "<string>",
"type": "<string>"
}
}

Get Task Status and Results

Query a task by task_id. When the task status is succeeded, the response automatically includes the first page of normalized results. Use cursor and limit on the same endpoint to read additional result pages.

Endpoint

GET https://api.socq.ai/v1/tasks/{task_id}
Use the next_cursor returned under results to read the next page:
GET https://api.socq.ai/v1/tasks/{task_id}?limit=50&cursor=NTY3ODkw

Response

{
  "code": 200,
  "data": {
    "task_id": "A1B2C3D4E5F6G7H8",
    "status": "succeeded",
    "result_count": 1,
    "error_message": null,
    "credits_amount": 0,
    "created_time": "2026-07-07T18:30:32",
    "finished_time": "2026-07-07T18:30:48",
    "results": {
      "limit": 50,
      "next_cursor": null,
      "has_more": false,
      "items": [
        {
          "id": "25025320",
          "platform": "instagram",
          "resource": "followers-count",
          "type": "profile_metrics",
          "username": "instagram",
          "name": "Instagram",
          "url": "https://www.instagram.com/instagram",
          "metrics": {
            "followers_count": 685829413,
            "following_count": 251,
            "posts_count": 8000
          },
          "collected_at": "2026-07-07T18:30:48",
          "extra": {}
        }
      ]
    }
  }
}

Response Fields

FieldTypeDescription
task_idstringTask identifier
statusstringqueued, running, succeeded, or failed
result_countintegerNumber of collected records
error_messagestringFailure reason when status is failed
credits_amountnumberCredits charged for the task
created_timestringTask creation time
finished_timestringTask completion time
resultsobjectPresent only when status is succeeded; contains paginated normalized records

Pagination

QueryTypeDefaultDescription
limitinteger50Number of records to return, max 500
cursorstringnullCursor from the previous results.next_cursor. Omit it for the first page.
While a task is queued, running, or failed, this endpoint returns task metadata without results.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

task_id
string
required

Task ID returned by the submit endpoint

Example:

"A1B2C3D4E5F6G7H8"

Query Parameters

cursor
string | null

Cursor returned by the previous data.results.next_cursor. Omit for the first page.

limit
integer
default:50

Maximum number of result records to return.

Required range: 1 <= x <= 500

Response

Task status and optional results

code
integer
Example:

200

data
object