# Surplus Intelligence X/Twitter User by Username Lookup

> Surplus Intelligence X/Twitter User by Username Lookup is a paid API for AI agents from www.surplusintelligence.ai, paid per call via x402, $0.0128/call, status unknown (last checked 2026-09-14).

Fetches Twitter/X user profile data by a given username using the Twitter API v2, billed per call via x402 micropayment.

## Facts

- Endpoint: GET https://www.surplusintelligence.ai/x402/api/twitter/v2/users/by/username/:username
- Price: $0.0128/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/www-surplusintelligence-ai-48f49ed1
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_rXw7c5jIq9m5rFMu8Cxou

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability www-surplusintelligence-ai-48f49ed1
```

Example prompt: Can you look up the Twitter profile for the username 'elonmusk' and tell me their user ID and account details?

## When to prefer this

Use this endpoint when you need to resolve a Twitter/X username (handle) to a structured user object including their numeric user ID, without needing tweet history or follower lists. Ideal for identity resolution, profile enrichment, or as a first step before calling other Twitter endpoints that require a user ID. Prefer this over the general user lookup endpoint when you have a username (not an ID) as your starting point.

## Known failure modes

- Username not found — returns errors array with 'Not Found Error'
- Invalid or missing username path parameter — returns 400 or validation error
- Payment failure or x402 micropayment not completed — request not processed
- Rate limiting from underlying Twitter API v2 — may return 429 or error response
- Private or suspended account — may return restricted data or error

## How this service works

X/Twitter API v2 via Surplus Intelligence: User by username (1 unit)

## Output

Returns a Twitter API v2 user object including the user's unique ID, display name, username, and associated account metadata for the queried username. May also include errors array if the username is not found.

## Example request

```json
{
 "input": {
  "type": "http",
  "method": "GET",
  "pathParams": {
   "username": "twitter"
  },
  "queryParams": {}
 }
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "pathParams": {
     "type": "object",
     "required": [
      "username"
     ],
     "properties": {
      "username": {
       "type": "string",
       "description": "X/Twitter username without @, e.g. x or elonmusk."
      }
     },
     "additionalProperties": false
    },
    "queryParams": {
     "type": "object",
     "properties": {},
     "additionalProperties": false
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "properties": {
      "data": {},
      "meta": {
       "type": "object"
      },
      "errors": {
       "type": "array"
      }
     },
     "additionalProperties": true
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "object",
 "required": [
  "data"
 ],
 "properties": {
  "data": {
   "type": "object",
   "required": [
    "id",
    "name",
    "username",
    "withheld"
   ],
   "properties": {
    "id": {
     "type": "string"
    },
    "name": {
     "type": "string"
    },
    "username": {
     "type": "string"
    },
    "withheld": {
     "type": "object",
     "required": [
      "country_codes"
     ],
     "properties": {
      "country_codes": {
       "type": "array",
       "items": {
        "type": "string"
       }
      }
     }
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/www-surplusintelligence-ai-48f49ed1/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from www.surplusintelligence.ai](https://www.zero.xyz/host/www.surplusintelligence.ai/llms.txt)