Retrieve a Task

POST https://maxaeo.ai/geoapi/geodata/developer/task/get

Reads the latest status of a task by task_id. Once the task succeeds, the response includes the full result. Doesn’t use any credits.

Parameters

Parameter	Type	Required	Description
`task_id`	string	Yes	The task ID returned by Submit a task or List tasks, up to 64 characters

Which tasks you can read: every task the same user submitted in their personal account, no matter which API key was used or whether it was submitted from the Playground in the Developer Console. If the key that submitted a task is disabled or deleted, you can still read the task with any other valid key.

Request example

curl -X POST "https://maxaeo.ai/geoapi/geodata/developer/task/get" \
  -H "Authorization: Bearer $MAXAEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "task_3f6c1d2e-8a4b-4c1f-9e2d-7b5a0c9d1e23"}'

import os
import time

import requests

URL = "https://maxaeo.ai/geoapi/geodata/developer/task/get"
HEADERS = {"Authorization": f"Bearer {os.environ['MAXAEO_API_KEY']}"}


def wait_task(task_id, interval=15):
    while True:
        data = requests.post(URL, headers=HEADERS, json={"task_id": task_id}, timeout=30).json()
        if data["ret"] != 1:
            raise RuntimeError(f"ret={data['ret']}: {data['msg']}")
        task = data["data"]["ent"]
        if task["status"] in ("succeeded", "failed", "canceled"):
            return task
        time.sleep(interval)


task = wait_task("task_3f6c1d2e-8a4b-4c1f-9e2d-7b5a0c9d1e23")
print(task["status"], task["answer"][:200])

const TASK_GET_URL = "https://maxaeo.ai/geoapi/geodata/developer/task/get";
const headers = {
  Authorization: `Bearer ${process.env.MAXAEO_API_KEY}`,
  "Content-Type": "application/json",
};

async function waitTask(taskId, intervalMs = 15_000) {
  for (;;) {
    const resp = await fetch(TASK_GET_URL, { method: "POST", headers, body: JSON.stringify({ task_id: taskId }) });
    const data = await resp.json();
    if (data.ret !== 1) throw new Error(`ret=${data.ret}: ${data.msg}`);
    const task = data.data.ent;
    if (["succeeded", "failed", "canceled"].includes(task.status)) return task;
    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }
}

const task = await waitTask("task_3f6c1d2e-8a4b-4c1f-9e2d-7b5a0c9d1e23");
console.log(task.status, task.answer.slice(0, 200));

Response

data.ent is a task object. Read it based on status:

Unfinished (queued / dispatching / pending / running): result fields are empty and credits is the reserved amount. Keep polling.
succeeded: answer holds the answer text, raw_result holds the structured result (sources, agent steps, media cards, and so on), and credits is the amount charged.
failed / canceled: the reason is in error_code and error_message, and credits is 0.

Example of a successful task (long text in answer, result_json, and similar fields is truncated):

{
  "ret": 1,
  "data": {
    "ent": {
      "thinking": false,
      "task_id": "task_3f6c1d2e-8a4b-4c1f-9e2d-7b5a0c9d1e23",
      "platform": "chatgpt",
      "query": "best mechanical keyboards for programmers",
      "status": "succeeded",
      "answer": "For programming, the best mechanical keyboards balance a comfortable switch feel, a practical layout, and good ergonomics for long sessions…",
      "result_json": "{\"taskId\":\"task_3f6c1d2e-8a4b-4c1f-9e2d-7b5a0c9d1e23\",\"platform\":\"chatgpt\",…}",
      "share_link": "https://chatgpt.com/share/…",
      "error_code": "",
      "error_message": "",
      "started_at": 1793018431,
      "finished_at": 1793018497,
      "created_at": 1793018425,
      "updated_at": 1793018503,
      "monitor_date": "2026-10-26",
      "priority": 2,
      "country": "",
      "credits": 6,
      "raw_result": {
        "taskId": "task_3f6c1d2e-8a4b-4c1f-9e2d-7b5a0c9d1e23",
        "platform": "chatgpt",
        "monitorDate": "2026-10-26",
        "query": "best mechanical keyboards for programmers",
        "success": true,
        "rawContent": "For programming, the best mechanical keyboards balance a comfortable switch feel, a practical layout, and good ergonomics for long sessions…",
        "references": [
          {
            "rank": 1,
            "title": "The Best Mechanical Keyboards for Programmers in 2026",
            "url": "https://www.example.com/best-keyboards-for-programmers",
            "snippet": "We tested switches, layouts, and keycaps to find the best keyboards for coding…",
            "source": "Example Tech",
            "domain": "www.example.com"
          },
          {
            "rank": 2,
            "title": "Keyboard layouts compared: TKL vs 75% vs 60%",
            "url": "https://blog.example.org/keyboard-layouts",
            "domain": "blog.example.org"
          }
        ],
        "shareLink": "https://chatgpt.com/share/…",
        "elapsedMs": "48213",
        "completedAt": "2026-10-26T12:41:37.512Z",
        "priority": 2
      }
    }
  }
}

Global platforms currently don’t distinguish whether a source was cited, so their references carry no cited field — that’s different from cited: false. See Working with Results.

Example of a task where the platform run failed:

{
  "ret": 1,
  "data": {
    "ent": {
      "thinking": false,
      "task_id": "task_9b2e4f60-1c3d-4e8a-b7f5-2d6c8a0e4b19",
      "platform": "gemini",
      "query": "how should a beginner choose their first pair of running shoes?",
      "status": "failed",
      "answer": "",
      "result_json": "{\"taskId\":\"task_9b2e4f60-1c3d-4e8a-b7f5-2d6c8a0e4b19\",\"error\":\"{\\\"zh\\\":\\\"平台抓取失败，本次不扣费，请稍后重试或更换平台\\\",\\\"en\\\":\\\"The platform crawl failed. No credits were charged. Please try again later or choose another platform.\\\"}\",…}",
      "share_link": "",
      "error_code": "crawl_failed",
      "error_message": "{\"zh\":\"平台抓取失败，本次不扣费，请稍后重试或更换平台\",\"en\":\"The platform crawl failed. No credits were charged. Please try again later or choose another platform.\"}",
      "started_at": 0,
      "finished_at": 1793007356,
      "created_at": 1793006882,
      "updated_at": 1793007363,
      "monitor_date": "2026-10-26",
      "priority": 2,
      "country": "",
      "credits": 0,
      "raw_result": {
        "taskId": "task_9b2e4f60-1c3d-4e8a-b7f5-2d6c8a0e4b19",
        "platform": "gemini",
        "monitorDate": "2026-10-26",
        "query": "how should a beginner choose their first pair of running shoes?",
        "error": "{\"zh\":\"平台抓取失败，本次不扣费，请稍后重试或更换平台\",\"en\":\"The platform crawl failed. No credits were charged. Please try again later or choose another platform.\"}",
        "elapsedMs": "2",
        "completedAt": "2026-10-26T09:35:56.853Z",
        "priority": 2
      }
    }
  }
}

error_message and raw_result.error are {"zh","en"} JSON strings — parse them to show the message in your user’s language, and branch on error_code rather than the wording.

The top-level thinking is the thinking mode requested at submission. Neither task above requested thinking, so raw_result has no thinking; when it’s requested and actually takes effect, raw_result includes "thinking": true. See Thinking mode.

Note that started_at can be 0: if a task jumps straight to its final result without a “running” status being observed, no start time is recorded. To measure duration, use finished_at - created_at (includes queueing) or raw_result.elapsedMs (execution only).

Polling tips

Polling about every 15 seconds is enough; polling more often usually returns the same status. See Task Lifecycle.
Tasks have no server-side deadline and can queue for a while. Once your own business timeout passes, you can set the task aside and fetch the result later by task_id.
Decide whether a task is finished from status alone. Don’t stop polling just because error_code isn’t empty.

Errors

`ret`	Cause
`1001`	`task_id` is empty or longer than 64 characters, or the body contains undefined fields
`1030`	Invalid API key
`1031`	The task doesn’t exist or doesn’t belong to the current user
`1003`	Account permission problem (rare) — please contact us
`-1`	Service temporarily unavailable — safe to retry