Obtener usuario por nombre | Documentación de API

# Get User By Username

Query a Twitter user profile by username and return a normalized X API v2-style user object.

GET https://api.apihop.ai/v1/twitter/users

Use `username` to query a user profile. This endpoint is useful when you only know a username and need the normalized `data.id` for timeline requests.

```text
GET https://api.apihop.ai/v1/twitter/users
```

## Authentication

All Twitter API endpoints require Bearer Token authentication.

```http
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

### `username` (string, required)

Twitter username. Both `elonmusk` and `@elonmusk` are accepted; the leading `@` is removed server-side.

### `user.fields` (string)

Comma-separated user fields, such as `created_at,description,public_metrics,verified`.

## Request Example

```bash
curl --request GET \
  "$API_BASE_URL/v1/twitter/users?username=elonmusk&user.fields=created_at,description,public_metrics,verified" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

## Response

### `data` (object, required)

Normalized user object.

### data fields

### `id` (string, required)

Unique user identifier. Prefer this value for timeline queries.

### `name` (string, required)

Display name.

### `username` (string, required)

Username without `@`.

### `created_at` (string)

ISO 8601 timestamp, returned when `user.fields=created_at` is requested.

### `description` (string)

User bio.

### `entities` (object)

Profile entities, such as URL descriptions and links.

### `location` (string)

Location in the user profile.

### `pinned_tweet_id` (string)

ID of the pinned tweet.

### `profile_banner_url` (string)

Profile banner URL.

### `profile_image_url` (string)

Profile image URL.

### `protected` (boolean)

Whether the account is protected.

### `public_metrics` (object)

Public user metrics.

### public_metrics fields

### `followers_count` (integer)

Number of followers.

### `following_count` (integer)

Number of accounts followed.

### `tweet_count` (integer)

Total number of tweets.

### `listed_count` (integer)

Number of lists containing the user. May be absent when the data source does not provide it.

### `url` (string)

Website URL in the user profile.

### `verified` (boolean)

Whether the account is verified.

### `verified_type` (string)

Verification type, such as `Business`.

### Success Example

```json
{
  "data": {
    "id": "44196397",
    "name": "Elon Musk",
    "username": "elonmusk",
    "created_at": "2009-06-02T20:12:29.000Z",
    "description": "Mars and cars",
    "public_metrics": {
      "followers_count": 10,
      "following_count": 20,
      "tweet_count": 40
    },
    "verified": true
  }
}
```

## Error Response

See [Error Codes and Troubleshooting](https://apihop.ai/en/docs/api-reference/errors) for the full code reference, protocol differences, and diagnostic steps.

```json
{
  "success": false,
  "error": {
    "code": 40000,
    "message": "Insufficient credit. Required: 100000, Available: 99999"
  },
  "requestId": "req_xxx"
}
```

## Usage Tips

- If you only know `username`, call this endpoint first
- If you plan to query a timeline, use the returned `data.id`
- If you only need avatar, bio, or follower counts, pass `user.fields` explicitly

Usa username para consultar un perfil. Este endpoint resulta útil cuando solo conoces un nombre de usuario y necesitas el data.id normalizado para solicitudes de cronología.

text

GET https://api.apihop.ai/v1/twitter/users

Autenticación

Todos los endpoints de la API de Twitter requieren autenticación mediante token Bearer.

http

Authorization: Bearer YOUR_API_KEY

Parámetros de consulta

usernamestringobligatorio

Nombre de usuario de Twitter. Se aceptan elonmusk y @elonmusk; el servidor elimina el @ inicial.

user.fieldsstring

Campos de usuario separados por comas, como created_at,description,public_metrics,verified.

Ejemplo de solicitud

bash

curl --request GET \
  "$API_BASE_URL/v1/twitter/users?username=elonmusk&user.fields=created_at,description,public_metrics,verified" \
  --header "Authorization: Bearer YOUR_API_KEY"

Respuesta

dataobjectobligatorio

Objeto de usuario normalizado.

Campos de data

idstringobligatorio

Identificador único del usuario. Prefiere este valor para consultar cronologías.

namestringobligatorio

Nombre visible.

usernamestringobligatorio

Nombre de usuario sin @.

created_atstring

Marca de tiempo ISO 8601, devuelta cuando se solicita user.fields=created_at.

descriptionstring

Biografía del usuario.

entitiesobject

Entidades del perfil, como descripciones de URL y enlaces.

locationstring

Ubicación en el perfil del usuario.

pinned_tweet_idstring

ID de la publicación fijada.

profile_banner_urlstring

URL de la imagen de portada del perfil.

profile_image_urlstring

URL de la imagen de perfil.

protectedboolean

Si la cuenta está protegida.

public_metricsobject

Métricas públicas del usuario.

Campos de public_metrics

followers_countinteger

Número de seguidores.

following_countinteger

Número de cuentas seguidas.

tweet_countinteger

Número total de publicaciones.

listed_countinteger

Número de listas que incluyen al usuario. Puede faltar si la fuente de datos no lo proporciona.

urlstring

URL del sitio web en el perfil del usuario.

verifiedboolean

Si la cuenta está verificada.

verified_typestring

Tipo de verificación, como Business.

Ejemplo correcto

json

{
  "data": {
    "id": "44196397",
    "name": "Elon Musk",
    "username": "elonmusk",
    "created_at": "2009-06-02T20:12:29.000Z",
    "description": "Mars and cars",
    "public_metrics": {
      "followers_count": 10,
      "following_count": 20,
      "tweet_count": 40
    },
    "verified": true
  }
}

Respuesta de error

Consulta Códigos de error y resolución de problemas para la referencia completa de códigos, diferencias de protocolo y pasos de diagnóstico.

json

{
  "success": false,
  "error": {
    "code": 40000,
    "message": "Insufficient credit. Required: 100000, Available: 99999"
  },
  "requestId": "req_xxx"
}

Consejos de uso

Si solo conoces username, llama primero a este endpoint
Si vas a consultar una cronología, usa el data.id devuelto
Si solo necesitas avatar, biografía o número de seguidores, envía user.fields explícitamente