جلب المستخدم باسم المستخدم | وثائق 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

استخدم username للاستعلام عن ملف مستخدم. تفيد نقطة النهاية هذه عندما تعرف اسم المستخدم فقط وتحتاج إلى data.id الموحد لطلبات المنشورات.

text

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

المصادقة

تتطلب جميع نقاط نهاية Twitter API المصادقة برمز Bearer.

http

Authorization: Bearer YOUR_API_KEY

معاملات الاستعلام

usernamestringمطلوب

اسم مستخدم Twitter. يقبل كل من elonmusk و@elonmusk؛ وتحذف @ الأولى من جانب الخادم.

user.fieldsstring

حقول مستخدم مفصولة بفواصل، مثل created_at,description,public_metrics,verified.

مثال طلب

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"

الاستجابة

dataobjectمطلوب

كائن مستخدم موحد.

حقول data

idstringمطلوب

معرف فريد للمستخدم. فضل هذه القيمة للاستعلام عن المنشورات.

namestringمطلوب

اسم العرض.

usernamestringمطلوب

اسم المستخدم دون @.

created_atstring

طابع زمني بصيغة ISO 8601، يعاد عند طلب user.fields=created_at.

descriptionstring

نبذة المستخدم.

entitiesobject

كيانات الملف، مثل أوصاف URL والروابط.

locationstring

الموقع في ملف المستخدم.

pinned_tweet_idstring

معرف التغريدة المثبتة.

profile_banner_urlstring

عنوان لافتة الملف.

profile_image_urlstring

عنوان صورة الملف.

protectedboolean

ما إذا كان الحساب محميا.

public_metricsobject

مقاييس المستخدم العامة.

حقول public_metrics

followers_countinteger

عدد المتابعين.

following_countinteger

عدد الحسابات المتابعة.

tweet_countinteger

إجمالي عدد التغريدات.

listed_countinteger

عدد القوائم التي تتضمن المستخدم. قد يغيب عندما لا يوفره مصدر البيانات.

urlstring

عنوان الموقع في ملف المستخدم.

verifiedboolean

ما إذا كان الحساب موثقا.

verified_typestring

نوع التوثيق، مثل Business.

مثال نجاح

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

استجابة الخطأ

راجع رموز الأخطاء وتشخيصها للمرجع الكامل للرموز واختلافات البروتوكولات وخطوات التشخيص.

json

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

نصائح الاستخدام

إذا كنت تعرف username فقط، فاستدع نقطة النهاية هذه أولا
إذا كنت تخطط للاستعلام عن المنشورات، فاستخدم data.id المعاد
إذا احتجت فقط إلى الصورة أو النبذة أو أعداد المتابعين، فمرر user.fields صراحة