POST

/api/v1/x/profile

Adaptive, high-reasoning profile of one X account

Profile a single X account using a high-reasoning Grok 4.5 agent that adaptively runs targeted X searches across the requested history until the fixed evidence goals — interests and beliefs, risk and trading behaviour, and reasoning style — are supported or the hard three-turn research ceiling is exhausted. The default and maximum window is 365 days. A synthesis pass returns evidenced interests, beliefs, tendencies, risk posture, information-processing style, and hints for tailoring recommendations. Every claim cites post_ids present in the returned evidence; unsupported claims are dropped. Accounts with fewer than 15 grounded posts return 404 and are not billed. Successful results are persisted in Neo4j and reused across callers while less than 30 days old when handle, focus, and lookback match; provider storage remains disabled.

Price $1.00Auth x-quotient-api-key or x402Limit 5/s · 60/min · 500/day

Parameters

None.

Request body

application/json, required

Field	Type	Description
handle required	string	X handle to profile, with or without a leading @. Pattern: ^@?[A-Za-z0-9_]{1,15}$
lookback_days	integer	Size of the trailing window to study. Defaults to 365 days and cannot exceed 365 days. Default: 365; Minimum: 14; Maximum: 365
focus	"general" \| "trading" \| "reasoning"	Reweights the same search toward speculative decision-making or toward information processing. Does not add a second search. Default: "general"

Responses

200: Evidence-grounded psychographic profile, newly researched or served from the shared cache while less than 30 days old

Field

Type

Description

handle

string

display_name

string | null

profile_url

string

quotient_metadata

QuotientXAccountMetadata

Quotient's account classification metadata. Reviewed expert status records Quotient classification provenance.

quotient_metadata fields

Field

Type

Description

handle

string

display_name

string | null

x_user_id

string | null

current_username

string | null

is_quotient_expert

boolean

quotient_expert

object | null

quotient_expert fields

Field	Type	Description
designation	"reviewed_expert"
policy_version	string \| null

window

object

window fields

Field	Type	Description
from_date	string	Format: date
to_date	string	Format: date
lookback_days	integer
post_count	integer	Distinct citation-grounded posts the profile is built from.

interests

object[]

interests fields

Field	Type	Description
post_ids	string[]
topic	string
weight	number	Relative prominence in the window, 0-1.

beliefs

object[]

beliefs fields

Field	Type	Description
post_ids	string[]
claim	string
confidence	string

tendencies

object[]

tendencies fields

Field	Type	Description
post_ids	string[]
trait	string
description	string

risk_profile

object | null

risk_profile fields

Field	Type	Description
post_ids	string[]
posture	string
time_horizon	string
position_sizing	string
reaction_to_loss	string

information_processing

object | null

How the account handles complex, ambiguous, or conflicting information.

information_processing fields

Field	Type	Description
post_ids	string[]
style	string
evidence_preference	string
handles_ambiguity	string
changes_mind_when	string

recommendation_hints

object | null

Direct inputs for tailoring suggestions to this person.

recommendation_hints fields

Field	Type	Description
market_categories	string[]
tone	string
avoid	string[]

observations

object[]

Raw retrieval findings before synthesis, tagged by angle, each citing its own post_ids.

observations fields

Field	Type	Description
dimension	string
statement	string
post_ids	string[]

evidence

object[]

Every grounded post the profile draws on. All post_ids resolve here.

evidence fields

Field	Type	Description
post_id	string
url	string
published_at	string \| null
excerpt	string

confidence

"low" | "medium" | "high"

gaps

string[]

What the window could not establish.

meta

object

401: Unauthorized

Field	Type	Description
error required	string	Error code
message required	string	Human-readable message
retry_after	integer	Seconds to wait (only on 429)
retryAfter	integer	Seconds to wait for owner-scoped forecast-request quota errors.
limit_scope	string	Quota scope that rejected the request, such as standard or x_research.
quotaScope	string	Stable forecast-request quota scope, such as venue_market_daily.
limit	integer	Configured bound for the forecast-request quota that was exceeded.

402: Payment Required

Field	Type	Description
error required	string	Error code
message required	string	Human-readable message
retry_after	integer	Seconds to wait (only on 429)
retryAfter	integer	Seconds to wait for owner-scoped forecast-request quota errors.
limit_scope	string	Quota scope that rejected the request, such as standard or x_research.
quotaScope	string	Stable forecast-request quota scope, such as venue_market_daily.
limit	integer	Configured bound for the forecast-request quota that was exceeded.

403: Insufficient credits for the requested route

Field	Type	Description
error required	string	Error code
message required	string	Human-readable message
retry_after	integer	Seconds to wait (only on 429)
retryAfter	integer	Seconds to wait for owner-scoped forecast-request quota errors.
limit_scope	string	Quota scope that rejected the request, such as standard or x_research.
quotaScope	string	Stable forecast-request quota scope, such as venue_market_daily.
limit	integer	Configured bound for the forecast-request quota that was exceeded.

404: The account has too little public posting in the window to profile (insufficient_post_history). The gateway does not bill or settle this response.

Field	Type	Description
error required	string	Error code
message required	string	Human-readable message
retry_after	integer	Seconds to wait (only on 429)
retryAfter	integer	Seconds to wait for owner-scoped forecast-request quota errors.
limit_scope	string	Quota scope that rejected the request, such as standard or x_research.
quotaScope	string	Stable forecast-request quota scope, such as venue_market_daily.
limit	integer	Configured bound for the forecast-request quota that was exceeded.

422: Invalid request body

Field	Type	Description
error required	string	Error code
message required	string	Human-readable message
retry_after	integer	Seconds to wait (only on 429)
retryAfter	integer	Seconds to wait for owner-scoped forecast-request quota errors.
limit_scope	string	Quota scope that rejected the request, such as standard or x_research.
quotaScope	string	Stable forecast-request quota scope, such as venue_market_daily.
limit	integer	Configured bound for the forecast-request quota that was exceeded.

429: The caller exceeded a per-second, per-minute, daily, or concurrency limit. No credits are debited and no x402 payment is settled for this response.

Field	Type	Description
error required	string	Error code
message required	string	Human-readable message
retry_after	integer	Seconds to wait (only on 429)
retryAfter	integer	Seconds to wait for owner-scoped forecast-request quota errors.
limit_scope	string	Quota scope that rejected the request, such as standard or x_research.
quotaScope	string	Stable forecast-request quota scope, such as venue_market_daily.
limit	integer	Configured bound for the forecast-request quota that was exceeded.

502: xAI X Search unavailable or not executed. Not billed.

Field	Type	Description
error required	string	Error code
message required	string	Human-readable message
retry_after	integer	Seconds to wait (only on 429)
retryAfter	integer	Seconds to wait for owner-scoped forecast-request quota errors.
limit_scope	string	Quota scope that rejected the request, such as standard or x_research.
quotaScope	string	Stable forecast-request quota scope, such as venue_market_daily.
limit	integer	Configured bound for the forecast-request quota that was exceeded.

503: X profiling is not configured

Field	Type	Description
error required	string	Error code
message required	string	Human-readable message
retry_after	integer	Seconds to wait (only on 429)
retryAfter	integer	Seconds to wait for owner-scoped forecast-request quota errors.
limit_scope	string	Quota scope that rejected the request, such as standard or x_research.
quotaScope	string	Stable forecast-request quota scope, such as venue_market_daily.
limit	integer	Configured bound for the forecast-request quota that was exceeded.

Set QUOTIENT_API_KEY in your shell and replace example identifiers with returned IDs before running a request.

curl

curl --request POST \
  --header "x-quotient-api-key: $QUOTIENT_API_KEY" \
  --header "content-type: application/json" \
  --data '{"handle":"vitalikbuterin","lookback_days":365,"focus":"trading"}' \
  'https://quotient-api-gateway.onrender.com/api/v1/x/profile'

200 · application/json

{
  "handle": "example",
  "display_name": "example",
  "profile_url": "example",
  "quotient_metadata": {
    "handle": "example",
    "display_name": "example",
    "x_user_id": "example",
    "current_username": "example",
    "is_quotient_expert": false,
    "quotient_expert": {
      "designation": "reviewed_expert",
      "policy_version": "example"
    }
  },
  "window": {
    "from_date": "2027-01-01",
    "to_date": "2027-01-01",
    "lookback_days": 0,
    "post_count": 0
  },
  "interests": [
    {
      "post_ids": [
        "example"
      ],
      "topic": "example",
      "weight": 0
    }
  ],
  "beliefs": [
    {
      "post_ids": [
        "example"
      ],
      "claim": "example",
      "confidence": "example"
    }
  ],
  "tendencies": [
    {
      "post_ids": [
        "example"
      ],
      "trait": "example",
      "description": "example"
    }
  ],
  "risk_profile": {
    "post_ids": [
      "example"
    ],
    "posture": "example",
    "time_horizon": "example",
    "position_sizing": "example",
    "reaction_to_loss": "example"
  },
  "information_processing": {
    "post_ids": [
      "example"
    ],
    "style": "example",
    "evidence_preference": "example",
    "handles_ambiguity": "example",
    "changes_mind_when": "example"
  },
  "recommendation_hints": {
    "market_categories": [
      "example"
    ],
    "tone": "example",
    "avoid": [
      "example"
    ]
  },
  "observations": [
    {
      "dimension": "example",
      "statement": "example",
      "post_ids": [
        "example"
      ]
    }
  ],
  "evidence": [
    {
      "post_id": "example",
      "url": "example",
      "published_at": "example",
      "excerpt": "example"
    }
  ],
  "confidence": "low",
  "gaps": [
    "example"
  ],
  "meta": {}
}