getabrain

Official Python SDK for GetABrain.ai — real human judgment as an API.

Install

pip install getabrain

Quickstart

from getabrain import GetABrain, InsufficientBalanceError

gab = GetABrain(api_key="gab_k_...", api_secret="gab_s_...")

# Submit a query (returns immediately)
query = gab.queries.create(
    type="ab_test",
    title="Which headline converts better?",
    content_data={
        "question": "Which is more compelling?",
        "variant_a": {"description": "Save 20% today"},
        "variant_b": {"description": "Your future self will thank you"},
    },
    required_responses=5,
    bid_amount_cents=25,
)

# Wait for humans to answer (polls for you)
try:
    responses = gab.queries.wait_for_responses(query["id"], min_responses=5, timeout_s=600)
    for r in responses:
        print(r["response_data"])
except InsufficientBalanceError:
    print("Top up your balance at https://getabrain.ai")

API

• gab.queries.create(type=..., title=..., content_data={...}, required_responses=..., bid_amount_cents=...)
• gab.queries.get(query_id) · gab.queries.list(status=..., limit=...) · gab.queries.cancel(query_id)
• gab.queries.wait_for_responses(query_id, min_responses=..., timeout_s=600, poll_interval_s=5)
• gab.responses.rate(query_id, response_id, score=5, feedback_text="...") · gab.responses.get_rating(query_id, response_id)
• gab.account.stats() · gab.account.balance() · gab.account.create_topup_link(amount_cents) (Stripe Checkout URL a human opens to fund the account; works from a test key too)

Query types: text, multiple_choice, rating_scale, image_comparison, ranking, yes_no, sentiment, image_selection, free_form_text, video_review, audio_review, image_analysis, ab_test, voice_capture, video_capture, photo_capture (also exported as getabrain.QUERY_TYPES).

Errors

All errors subclass GetABrainError: ValidationError, AuthError, InsufficientBalanceError, ForbiddenError, NotFoundError, ConflictError, RateLimitError (.retry_after_ms), ServerError, TimeoutError, NetworkError.

InsufficientBalanceError.payment_required carries the raw x402 v2 payment-terms body when the server returned one (e.g. err.payment_required["accepts"][0]["extra"]["deposit_endpoint"]) -- see "Stablecoin / x402 payments" below.

Stablecoin / x402 payments

Balance top-ups also accept USDC (Base/Solana/Tempo), not just cards, via a Stripe crypto PaymentIntent -- settlement is asynchronous (on-chain confirmation + Stripe capture, not instant). The SDK doesn't wrap the billing endpoints yet (gab.account.balance() is read-only), so call the REST endpoint directly:

import requests

# Mint a real, one-time on-chain USDC deposit address for $50
res = requests.post(
    "https://getabrain.ai/api/v1/requestor/billing/crypto-checkout",
    headers={"X-API-Key": api_key, "X-API-Secret": api_secret},
    json={"amount_cents": 5000, "network": "base"},
)
deposit_details = res.json()["deposit_details"]  # send USDC here, then poll gab.account.balance()

Full API docs: https://getabrain.ai/docs/api