Submit a Task

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

Submits one question to one AI platform. The endpoint returns the new task right away (status queued) along with its task_id; use Retrieve a task to get the result.

Every call creates a new task. A successful task is charged at the price in effect when you submitted it. That amount is reserved at submission and released if the task fails or is canceled.

Parameters

Parameter	Type	Required	Description
platform	string	Yes	Platform ID, such as chatgpt or perplexity. See List platforms for valid values; platforms whose platform_status is maintenance can’t be submitted to. Case-insensitive, up to 64 characters
query	string	Yes	The question to ask. Up to 4,096 characters after trimming leading and trailing whitespace. Must contain visible text and no control characters other than line feed, carriage return, and tab
priority	integer	No	1 = P1 Priority, 2 = P2 Standard. Omitted or 0 means P2. The tiers queue differently and are priced differently — see Priority
thinking	boolean	No	Whether to request the platform’s thinking mode. Defaults to false. Must be a JSON boolean. See below
country	string	No	Two-letter country code (ISO 3166-1 alpha-2) such as US or JP, case-insensitive. Only affects the exit location for global platforms — see Exit country
monitor_date	string	No	The task’s business date, YYYY-MM-DD; defaults to today in China Standard Time (UTC+8). Also accepts an RFC 3339 timestamp with an offset (such as 2026-10-26T09:30:00-07:00), which is converted to the UTC+8 date. Doesn’t affect when the task runs — see What monitor_date means
wait_seconds	integer	No	Seconds to wait synchronously, 0–120. Defaults to 0 (return immediately). See below

No other fields are accepted; any undefined field returns 1001.

Synchronous wait: wait_seconds

• 0 (default): returns immediately with the task in queued.
• 1–120: the server checks the task every 2 seconds for up to this long. As soon as the task reaches a final status (succeeded, failed, or canceled) it returns; if time runs out first, it returns the task in whatever status it’s in.

When you use a synchronous wait:

• Set your HTTP client timeout longer than wait_seconds — leave at least 15 extra seconds.
• The returned task may still be unfinished, so your code must be able to keep polling by task_id.
• If the connection drops while waiting, the task itself isn’t affected — recover its task_id as described in Avoiding duplicate submissions.

Thinking mode: thinking

Pass "thinking": true to ask the platform to answer in its thinking mode, such as ChatGPT’s thinking or DeepSeek’s DeepThink:

curl -X POST "https://maxaeo.ai/geoapi/geodata/developer/task/submit" \
  -H "Authorization: Bearer $MAXAEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform": "chatgpt", "query": "best mechanical keyboards for programmers", "thinking": true}'

• Platforms without a thinking switch run with thinking off, without an error. Whether thinking was actually on is raw_result.thinking in the result; the top-level thinking in the response only echoes your request.
• It’s noticeably slower and costs nothing extra.

See Thinking mode for which platforms support it.

Request example

cURL

curl -X POST "https://maxaeo.ai/geoapi/geodata/developer/task/submit" \
  -H "Authorization: Bearer $MAXAEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "chatgpt",
    "query": "best mechanical keyboards for programmers",
    "priority": 2
  }'

Python

import os

import requests

resp = requests.post(
    "https://maxaeo.ai/geoapi/geodata/developer/task/submit",
    headers={"Authorization": f"Bearer {os.environ['MAXAEO_API_KEY']}"},
    json={"platform": "chatgpt", "query": "best mechanical keyboards for programmers", "priority": 2},
    timeout=30,
)
data = resp.json()
if data["ret"] != 1:
    raise RuntimeError(f"ret={data['ret']}: {data['msg']}")
task = data["data"]["ent"]
print(task["task_id"], task["status"], task["credits"])

Node.js

const resp = await fetch("https://maxaeo.ai/geoapi/geodata/developer/task/submit", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAXAEO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ platform: "chatgpt", query: "best mechanical keyboards for programmers", priority: 2 }),
});
const data = await resp.json();
if (data.ret !== 1) throw new Error(`ret=${data.ret}: ${data.msg}`);
const task = data.data.ent;
console.log(task.task_id, task.status, task.credits);

Response

data.ent is a task object. Without a synchronous wait, a freshly submitted task has:

• status set to queued;
• a task_id of the form task_ followed by a UUID — use it for all later lookups;
• credits set to the reserved amount, i.e. the current price for that platform and tier;
• thinking set to the thinking mode you requested (false if you didn’t pass it);
• empty result fields such as answer and result_json, and no raw_result.

{
  "ret": 1,
  "data": {
    "ent": {
      "thinking": false,
      "task_id": "task_3f6c1d2e-8a4b-4c1f-9e2d-7b5a0c9d1e23",
      "platform": "chatgpt",
      "query": "best mechanical keyboards for programmers",
      "status": "queued",
      "answer": "",
      "result_json": "",
      "share_link": "",
      "error_code": "",
      "error_message": "",
      "started_at": 0,
      "finished_at": 0,
      "created_at": 1793018425,
      "updated_at": 1793018425,
      "monitor_date": "2026-10-26",
      "priority": 2,
      "country": "",
      "credits": 6
    }
  }
}

Errors

These errors happen before a task is created: no task is created and no credits are charged.

ret	Cause	What to do
1001	Invalid parameters; msg names the field — for example query is empty or too long, priority isn’t 1 or 2, country isn’t two letters, monitor_date is malformed, or wait_seconds is outside 0–120. A body with undefined fields, or a field of the wrong type (such as thinking sent as the string "true"), also returns 1001	Fix the parameters
1022	Developer API billing isn’t enabled	Contact sales
1023	Available credits don’t cover this task’s price	Top up, or use a cheaper platform or tier
1024	Too many tasks in progress	Retry after some tasks finish
1025	Submitting too fast	Slow down and retry with backoff
1029	The platform isn’t available (no price configured, or retired) or is under maintenance	Refresh the platform list and pick another platform
1030	Invalid API key	Check your key
1003	Account permission problem (rare)	Contact us
-1	Service temporarily unavailable	The task may have been created. Check with List tasks before deciding whether to resubmit

There’s one more case: the request passes validation and a task is created, but dispatching or running it fails afterwards. The submit call returns success, the task ends up with status failed, and the reason is in error_code (for example crawler_rejected when a platform has been retired). It isn’t charged either. See Error Handling.

Don't blindly retry submissions

Submitting isn’t idempotent: repeated calls create multiple tasks, and each one is charged if it succeeds. If a request times out, the connection drops, or you get -1, first check the task list by query text and time to see whether the task was created. See When a submission’s outcome is unknown for the full approach.