Skip to main content

LLM API reference

Ask ChatGPT and Gemini through one endpoint. Authentication, submitting questions, polling for results, credits and limits.

Written by NodeMaven

Ask ChatGPT and Gemini through one endpoint, priced only for what actually comes back.

The LLM API sends your prompts to ChatGPT and Gemini with country-level targeting, then hands you the rendered answer through three plain REST endpoints. A credit is spent only when a query actually succeeds - a failed one refunds itself automatically, no ticket required.

api.nodemaven.com

x-api-key header

dashboard → Profile

JSON

submit & poll

request auth

where your key lives

everywhere

Quickstart flow

Four steps, start to finish - from copying your key to reading back an answer.

1

2

3

4

Get your API key

Your key lives in the dashboard's Profile section. Every call below sends it as a Bearer-style header, prefixed x-api-key instead of Bearer.

dashboard → Profile

Submit your questions

One call can carry several prompts across several platforms, all aimed at one country/region/city

POST /submit/

Poll for results

Every row starts pending. Poll the same batch until each one turns success or failed.

GET /results/{request_id}/

Read the answer

A successful row's raw_response.text is the rendered answer. Failed rows refund their own credit.

raw_response.text

This is the whole surface. Three endpoints, total: check your balance any time before you submit, submit a batch, poll it. There's no fourth thing to learn.

Authentication

One key, one header - but note the prefix isn't Bearer.

Where to get it

How to send it

Your API key is shown in the Profile section of the NodeMaven dashboard - the same key used across NodeMaven's base API, not a separate token per product.

Authorization: x-api-key <your key> on every request. Note the literal prefix is x-api-key, not Bearer.

# Every request uses the key from your dashboard's Profile section

curl https://api.nodemaven.com/v2/base/llm/balance/ \   -H "Authorization: x-api-key YOUR_API_KEY"

Purchase a credit pack before you integrate. All three endpoints below - including balance - return 403 until your account has at least one completed credit-pack purchase. Free monthly credits alone don't unlock the API; that gate only applies to the dashboard's own GEO page.

Errors & status codes

The body shape depends on why a request failed — a validation problem reports field-by-field, an operational one reports a single message.

400 · bad input (field-keyed)

{
  "country": [
    "ChatGPT and Gemini are not available in 'ru'"
  ]
}

402 · insufficient credits

{
  "error":
    "Insufficient credits: required 3, available 1"
}

Status

Meaning

Notes

400

Bad request

Malformed JSON, too many/too-long questions, an unknown platform, a duplicated platform, or a country the model isn't available in. Body is field-keyed: {"<field>": ["…"]}.

401

Unauthorized

Missing or invalid Authorization header.

402

Payment required

Not enough credits to cover this submit's full question × platform count. Nothing is written or charged.

403

Forbidden

No completed credit-pack purchase on the account yet. Body: {"detail": "…"}.

404

Not found

request_id unknown, or belongs to another account — ownership never leaks as a distinct error. Body: {"error": "Not found"}.

Limits

Defaults below - ask support if your workload needs more headroom.

Limit

Default

Questions per submit

20

Characters per question

2,047

Submit rate

20 / minute

Balance & results rate

100 / minute

Free credits

2 / calendar month

Platforms & targeting

Every question is sent to one or more platforms, aimed at a country and, optionally, a region and city.

Platform value

Sent as

Status

chatgpt

ChatGPT

Available

gemini

Gemini

Available

perplexity

Perplexity

Currently unavailable

perplexity is still a valid value in the request schema, but the platform is currently unavailable - leave it out of platforms for now. It'll be listed as Available here once that changes.

Not every country is available. country is a required, lowercase, 2-letter ISO code - but a small set of countries return a 400 because the underlying models aren't offered there at all. Check the response's country field for the exact message rather than hardcoding a list, since availability is enforced server-side and can change.

region and city are both optional and both normalized for you - send a region's display name or its code, and a city in any case, and the request still resolves correctly.

Credits

One credit is spent per question × platform pair, upfront - and refunded automatically if that specific row fails.

GET /api/v2/base/llm/balance/ x-api-key

Your current balance. Also grants this month's free credits automatically, the first time you check in a given calendar month — nothing to request separately.

200 Response

{ "balance": 7 }

200 ok

403 no purchase yet

Queries

Submit a batch, then poll the same request_id until every row leaves pending.

POST /api/v2/base/llm/submit/ x-api-key

Charges questions × platforms credits and returns immediately — every row starts pending, nothing here is the final answer yet.

Field

Description

questions

REQUIRED

Array of prompt strings, up to 20 of them, 2,047 characters each.

platforms

REQUIRED

Array of chatgpt / gemini / perplexity, no duplicates — see availability.

country

REQUIRED

Lowercase 2-letter ISO code — see Platforms & targeting.

region

OPTIONAL

State/province, name or code.

city

OPTIONAL

Any case — normalized server-side.

REQUEST BODY

{
  "questions": [
    "What are the best residential proxy providers in 2026?"
  ],
  "platforms": ["chatgpt", "gemini"],
  "country": "us",
  "region": "CA",
  "city": "Los Angeles"
}

200 Response 

{
  "request_id": "7c1e…b0a4",
  "results": [
    {
      "id": "9f2a…",
      "platform": "chatgpt",
      "status": "pending",
      "raw_response": null
    },
    "…"
  ]
}

200 accepted, all rows pending

400 bad questions / platform / country

402 insufficient credits

403 no purchase yet

GET /api/v2/base/llm/results/{request_id}/ x-api-key

Every row from one submit, by its shared request_id. Call this again a few seconds later for whatever's still pending.

200 Response 

{
  "request_id": "7c1e…b0a4",
  "results": [
    {
      "id": "9f2a…", "platform": "chatgpt",
      "question": "What are the best residential proxy providers in 2026?",
      "country": "us", "region": "CA", "city": "Los Angeles",
      "status": "success",
      "raw_response": {
        "text": "For scale, the most consistently well-reviewed…",
        "used_html_fallback": false
      },
      "created": "2026-09-08T09:14:02Z",
      "updated": "2026-09-08T09:15:19Z"
    },
    {
      "id": "c48d…", "platform": "gemini",
      "…": "…", "status": "pending", "raw_response": null
    }
  ]
}

A failed row's credit has already been refunded by the time you see it — raw_response stays null, there's nothing else to read.

200 - check each row's own status

404 unknown request_id, or not yours

Polling for results

There's no webhook - results only ever arrive by asking again.

How long it takes

Most rows resolve in 20–90 seconds, occasionally longer — a real Chrome session is rendering the answer on the other end. Poll every few seconds rather than continuously.

The three states

pending → still rendering. success → read raw_response.text. failed → already refunded, nothing to retry manually.

Billing timing

Credits are charged at submit, not on success — a row that later fails refunds itself the moment it's marked failed, before you even poll.

Batching platforms

One request_id can hold rows across every platform you asked for — poll it once and read whichever rows have already turned.

Full walkthrough

Every step above, chained into one script: check your balance, ask two platforms the same question, wait it out, then read both answers.

#!/bin/bash
# Your key, copied from the dashboard's Profile section.
TOKEN="$NM_API_KEY"

# 1. check your balance (this also grants this month's free credits, if due)
curl -s https://api.nodemaven.com/v2/base/llm/balance/ \
  -H "Authorization: x-api-key $TOKEN"

# 2. submit one question to two platforms, targeted at Los Angeles
RESPONSE=$(curl -s -X POST https://api.nodemaven.com/v2/base/llm/submit/ \
  -H "Authorization: x-api-key $TOKEN" -H "Content-Type: application/json" \
  -d '{"questions":["What are the best residential proxy providers in 2026?"],"platforms":["chatgpt","gemini"],"country":"us","region":"CA","city":"Los Angeles"}')
REQUEST_ID=$(echo $RESPONSE | jq -r .request_id)

# 3. poll until nothing is left pending
until [ "$(curl -s https://api.nodemaven.com/v2/base/llm/results/$REQUEST_ID/ \
  -H "Authorization: x-api-key $TOKEN" | jq '[.results[] | select(.status=="pending")] | length')" = "0" ]; do
  sleep 5
done

# 4. read both answers
curl -s https://api.nodemaven.com/v2/base/llm/results/$REQUEST_ID/ \
  -H "Authorization: x-api-key $TOKEN" \
  | jq -r '.results[] | "\(.platform) [\(.status)]: \(.raw_response.text // "-")"'

LLM API · NodeMaven · questions: [email protected]

Did this answer your question?

Related Articles