List Tasks

POST https://maxaeo.ai/geoapi/geodata/developer/task/key/list

Pages through the tasks submitted with the current API key, newest first. List items don’t include the answer; call Retrieve a task when you need the result. Doesn’t use any credits.

Main uses:

• Recovering a task_id: when a submit request timed out or your process crashed and you’re not sure the task was created, look it up by query text and time instead of submitting again.
• Reconciliation and audits: page through a time range or status to total up credits for successful tasks and find failed ones.

Parameters

All optional.

Parameter	Type	Description
page	integer	Page number, starting at 1. Defaults to 1
page_size	integer	Items per page. Defaults to 20, maximum 100
start_time	integer	Lower bound on submission time (Unix seconds, inclusive)
end_time	integer	Upper bound on submission time (Unix seconds, exclusive); must be greater than start_time
platform	string	Only tasks for this platform
status	string	Only tasks in this status: queued, dispatching, pending, running, succeeded, failed, canceled. pending returns all three waiting statuses — queued, dispatching, and pending — and each item’s status is still its actual status; other values match exactly
keyword	string	If it starts with task_, matches the task ID exactly; otherwise matches tasks whose query contains the text. Up to 256 characters

What's included

Only tasks submitted with this exact key are listed. Tasks submitted with your other keys or from the Playground in the Developer Console aren’t in the list, but you can still read them by task_id with Retrieve a task. Rolling a key creates a new key, so tasks submitted before the roll don’t appear in the new key’s list.

Request example

Find tasks from the last hour whose query contains “mechanical keyboard”:

cURL

curl -X POST "https://maxaeo.ai/geoapi/geodata/developer/task/key/list" \
  -H "Authorization: Bearer $MAXAEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"keyword\": \"mechanical keyboard\", \"start_time\": $(($(date +%s) - 3600)), \"page_size\": 10}"

Python

import os
import time

import requests

resp = requests.post(
    "https://maxaeo.ai/geoapi/geodata/developer/task/key/list",
    headers={"Authorization": f"Bearer {os.environ['MAXAEO_API_KEY']}"},
    json={"keyword": "mechanical keyboard", "start_time": int(time.time()) - 3600, "page_size": 10},
    timeout=30,
)
data = resp.json()
if data["ret"] != 1:
    raise RuntimeError(f"ret={data['ret']}: {data['msg']}")
for item in data["data"]["ent"]["items"]:
    print(item["task_id"], item["status"], item["query"])

Node.js

const resp = await fetch("https://maxaeo.ai/geoapi/geodata/developer/task/key/list", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MAXAEO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    keyword: "mechanical keyboard",
    start_time: Math.floor(Date.now() / 1000) - 3600,
    page_size: 10,
  }),
});
const data = await resp.json();
if (data.ret !== 1) throw new Error(`ret=${data.ret}: ${data.msg}`);
for (const item of data.data.ent.items) {
  console.log(item.task_id, item.status, item.query);
}

Response

Fields in data.ent:

Field	Type	Description
total	integer	Total number of matching tasks
page	integer	Current page number
page_size	integer	Items per page
items	TaskItem[]	Tasks on this page, newest first

TaskItem is a slimmed-down task object. It doesn’t include answer, result_json, share_link, raw_result, or updated_at:

Field	Type	Description
task_id	string	Task ID
status	string	Task status
platform	string	Platform ID
query	string	The question
priority	integer	Priority at submission, 1 or 2
country	string	Requested exit country (uppercase), empty if not specified
thinking	boolean	The thinking mode requested at submission; to see whether it was actually on, read raw_result.thinking with Retrieve a task
monitor_date	string	Business date, YYYY-MM-DD
credits	integer	Credits charged if succeeded, reserved if unfinished, 0 if failed or canceled
error_code	string	Task-level error code — see Error Handling
error_message	string	Error message, a {"zh","en"} JSON string
created_at	integer	Submission time (Unix seconds)
started_at	integer	When execution started; 0 if not recorded
finished_at	integer	When the task finished; 0 if unfinished

{
  "ret": 1,
  "data": {
    "ent": {
      "total": 2,
      "page": 1,
      "page_size": 10,
      "items": [
        {
          "thinking": false,
          "task_id": "task_3f6c1d2e-8a4b-4c1f-9e2d-7b5a0c9d1e23",
          "status": "succeeded",
          "platform": "chatgpt",
          "query": "best mechanical keyboards for programmers",
          "priority": 2,
          "country": "",
          "monitor_date": "2026-10-26",
          "credits": 6,
          "error_code": "",
          "error_message": "",
          "created_at": 1793018425,
          "started_at": 1793018431,
          "finished_at": 1793018497
        },
        {
          "thinking": false,
          "task_id": "task_5a7d9c1b-3e2f-4d6a-8b0c-9e1f2a3b4c5d",
          "status": "pending",
          "platform": "perplexity",
          "query": "mechanical keyboard vs membrane keyboard for coding",
          "priority": 2,
          "country": "US",
          "monitor_date": "2026-10-26",
          "credits": 5,
          "error_code": "",
          "error_message": "",
          "created_at": 1793018390,
          "started_at": 0,
          "finished_at": 0
        }
      ]
    }
  }
}

Paging and reconciliation

• The list is sorted newest first, so if new tasks are submitted while you’re paging, later pages can repeat items from earlier pages. For reconciliation, pin end_time (for example, to when you started) and page within that fixed window.
• To total spend for a period, filter by status succeeded and sum credits.

Errors

ret	Cause
1001	Invalid parameters: page or page_size out of range, end_time not greater than start_time, a negative time, a status value not in the list, a keyword that’s too long, or undefined fields in the body
1003	Account permission problem (rare) — please contact us
1030	Invalid API key
-1	Service temporarily unavailable — safe to retry