Consultar usuário pelo nome de usuário | Documentação de APIs

# 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

Use username para consultar um perfil de usuário. Este endpoint é útil quando você só conhece o nome de usuário e precisa do data.id normalizado para consultas da linha do tempo.

text

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

Autenticação

Todos os endpoints da API do Twitter exigem autenticação com token Bearer.

http

Authorization: Bearer YOUR_API_KEY

Parâmetros de consulta

usernamestringobrigatório

Nome de usuário do Twitter. Tanto elonmusk quanto @elonmusk são aceitos; o @ inicial é removido no servidor.

user.fieldsstring

Campos de usuário separados por vírgulas, como created_at,description,public_metrics,verified.

Exemplo de requisição

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"

Resposta

dataobjectobrigatório

Objeto de usuário normalizado.

Campos de data

idstringobrigatório

Identificador exclusivo do usuário. Prefira este valor para consultas da linha do tempo.

namestringobrigatório

Nome de exibição.

usernamestringobrigatório

Nome de usuário sem @.

created_atstring

Data e hora em ISO 8601, retornadas quando user.fields=created_at é solicitado.

descriptionstring

Biografia do usuário.

entitiesobject

Entidades do perfil, como descrições de URLs e links.

locationstring

Localização no perfil do usuário.

pinned_tweet_idstring

ID do tweet fixado.

profile_banner_urlstring

URL do banner do perfil.

profile_image_urlstring

URL da imagem do perfil.

protectedboolean

Se a conta é protegida.

public_metricsobject

Métricas públicas do usuário.

Campos de public_metrics

followers_countinteger

Número de seguidores.

following_countinteger

Número de contas seguidas.

tweet_countinteger

Número total de tweets.

listed_countinteger

Número de listas que incluem o usuário. Pode estar ausente quando a fonte de dados não o fornece.

urlstring

URL do site no perfil do usuário.

verifiedboolean

Se a conta é verificada.

verified_typestring

Tipo de verificação, como Business.

Exemplo de sucesso

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
  }
}

Resposta de erro

Consulte Códigos de erro e solução de problemas para a referência completa, diferenças de protocolo e etapas de diagnóstico.

json

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

Dicas de uso

Se você só conhece username, chame este endpoint primeiro
Se pretende consultar uma linha do tempo, use o data.id retornado
Se precisar apenas do avatar, da biografia ou do número de seguidores, envie user.fields explicitamente