Quickstart

This page takes you from zero to your first answer: create an API key → list available platforms → submit a question → poll for the result → read the answer. All you need is a terminal.

Before you begin

• Sign in to the Developer Console with your MaxAEO account. Your account needs a credit balance to submit tasks. You get 1,000 free credits that never expire on first use — enough to work through this page. See Getting credits.
• Listing platforms and retrieving tasks are free; only successful tasks cost credits — see Billing & Credits.

1. Create an API key

   Sign in to the Developer Console, open API Keys, and click Create API key. Give it a name (for example, “Local testing”) and pick an expiration.

   Once it’s created, a dialog shows the full key — a string that starts with gdev_. The full key is shown only once. Copy it and store it in an environment variable:

   export MAXAEO_API_KEY="gdev_your_full_key"

   For everything else you can do with keys, see Manage API Keys.

2. List the available platforms

   Start with the simplest request to confirm the key works and get each platform’s ID and price:

   curl -X POST "https://maxaeo.ai/geoapi/geodata/developer/platforms/get" \
     -H "Authorization: Bearer $MAXAEO_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{}'

   Response (excerpt):

   {
     "ret": 1,
     "data": {
       "ent": {
         "platforms": ["chatgpt", "gemini", "claude", "perplexity", "…"],
         "items": [
           {
             "platform": "chatgpt",
             "region": "overseas",
             "platform_status": "normal",
             "p1_credits": 12,
             "p2_credits": 6,
             "has_stats": true,
             "success_rate": 0.95,
             "p50_duration_seconds": 58,
             "sample_count": 112,
             "stats_updated_at": 1793018400
           }
         ]
       }
     }
   }

   ret equal to 1 means success. When you submit a task, set platform to one of the IDs in platforms (platforms whose platform_status is maintenance aren’t accepting tasks). p1_credits / p2_credits are the credits charged per successful call at each priority tier (the numbers above are illustrative — rely on the live response).

   If you get {"ret":1030, …}, the key is invalid. Check that the environment variable holds the full key and that the key hasn’t been disabled — see Authentication.

3. Submit a task

   Ask ChatGPT a question. If you omit priority, the task runs and is billed at P2 Standard:

   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"}'

   The endpoint returns the task right away, with status queued:

   {
     "ret": 1,
     "data": {
       "ent": {
         "task_id": "task_3f6c1d2e-8a4b-4c1f-9e2d-7b5a0c9d1e23",
         "platform": "chatgpt",
         "query": "best mechanical keyboards for programmers",
         "status": "queued",
         "priority": 2,
         "credits": 6,
         "…": "…"
       }
     }
   }

   Save the task_id. At this point credits is the reserved amount: it’s only charged if the task succeeds, and released if it fails or is canceled.

4. Poll for the result

   Check every 15 seconds until status becomes succeeded, failed, or canceled:

   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"}'

   Fetching the answer itself usually takes tens of seconds to two minutes, plus queue time; it can take longer when a platform is busy. The intermediate statuses dispatching, pending, and running are all normal — just keep polling. See Task Lifecycle.

5. Read the answer

   Once the task succeeds, the response contains:

   • answer: the AI’s raw answer (Markdown), with the platform’s own citation markers preserved.
   • raw_result.references: the cited sources; cited: true means the answer text actually cites that source.
   • share_link: the platform’s share link (empty if the platform doesn’t provide one).
   • credits: the credits actually charged.

   Field definitions are in The Task Object; parsing tips are in Working with Results.

Complete example

The scripts below chain submit, poll, and read together. The API key is read from the MAXAEO_API_KEY environment variable.

Python

quickstart.py

import os
import time

import requests

BASE_URL = "https://maxaeo.ai/geoapi/geodata/developer"
HEADERS = {"Authorization": f"Bearer {os.environ['MAXAEO_API_KEY']}"}
TERMINAL = ("succeeded", "failed", "canceled")


def call(path, body):
    resp = requests.post(BASE_URL + path, headers=HEADERS, json=body, timeout=30)
    resp.raise_for_status()
    data = resp.json()
    if data["ret"] != 1:
        raise RuntimeError(f"ret={data['ret']}: {data.get('msg')}")
    return data["data"]["ent"]


task = call("/task/submit", {"platform": "chatgpt", "query": "best mechanical keyboards for programmers"})
print("Submitted", task["task_id"])

while task["status"] not in TERMINAL:
    time.sleep(15)
    task = call("/task/get", {"task_id": task["task_id"]})
    print("Status", task["status"])

if task["status"] == "succeeded":
    print(task["answer"])
    for ref in (task.get("raw_result") or {}).get("references", []):
        if ref.get("cited") is True:
            print(ref.get("rank"), ref.get("title"), ref.get("url"))
    print("Credits charged", task["credits"])
else:
    print("Task did not succeed", task["error_code"], task["error_message"])

Run it: pip install requests && python quickstart.py

Node.js

quickstart.mjs

const BASE_URL = "https://maxaeo.ai/geoapi/geodata/developer";
const headers = {
  Authorization: `Bearer ${process.env.MAXAEO_API_KEY}`,
  "Content-Type": "application/json",
};
const TERMINAL = ["succeeded", "failed", "canceled"];

async function call(path, body) {
  const resp = await fetch(BASE_URL + path, { method: "POST", headers, body: JSON.stringify(body) });
  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
  const data = await resp.json();
  if (data.ret !== 1) throw new Error(`ret=${data.ret}: ${data.msg}`);
  return data.data.ent;
}

let task = await call("/task/submit", { platform: "chatgpt", query: "best mechanical keyboards for programmers" });
console.log("Submitted", task.task_id);

while (!TERMINAL.includes(task.status)) {
  await new Promise((resolve) => setTimeout(resolve, 15_000));
  task = await call("/task/get", { task_id: task.task_id });
  console.log("Status", task.status);
}

if (task.status === "succeeded") {
  console.log(task.answer);
  for (const ref of task.raw_result?.references ?? []) {
    if (ref.cited === true) console.log(ref.rank, ref.title, ref.url);
  }
  console.log("Credits charged", task.credits);
} else {
  console.log("Task did not succeed", task.error_code, task.error_message);
}

Run it: node quickstart.mjs (requires Node.js 18 or later, which ships with fetch)

cURL

# 1. Submit and capture the task_id (requires jq)
TASK_ID=$(curl -s -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"}' | jq -r '.data.ent.task_id')
echo "Submitted $TASK_ID"  # "null" means the submission failed; rerun the submit command alone to see ret and msg

# 2. Check every 15 seconds until the task reaches a final status
while true; do
  RESP=$(curl -s -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_ID\"}")
  STATUS=$(echo "$RESP" | jq -r 'if .ret == 1 then .data.ent.status else "error" end')
  echo "Status $STATUS"
  case "$STATUS" in succeeded|failed|canceled) break ;; error) echo "$RESP"; break ;; esac
  sleep 15
done

# 3. Print the answer
echo "$RESP" | jq -r '.data.ent.answer'

Want to skip the polling loop?

Add "wait_seconds": 60 (up to 120) when you submit, and the endpoint waits for the task to finish before responding. If it’s still running when time runs out, you get the current status back and still need to keep polling by task_id. See Submit a Task.

Next steps

Platforms, Priority & CountryIDs for all 18 platforms, how to choose between P1 and P2, and the country parameter.

Error HandlingRequest-level and task-level error codes, plus retry strategies.

Production ChecklistBefore moving from a script to production, check security, reliability, and cost.

Connect via MCPCall it from your AI client without writing code.