داده‌های X

عملیات مناسب برای داده‌ای را که نیاز دارید انتخاب کنید. هر پنج پایان‌نقطه از POST استفاده می‌کنند و JSON را در ریشه برمی‌گردانند، بدون یک پوشش مشترک data.

تمام نمونه‌ها از FELO_API_KEY از نمای کلی استفاده می‌کنند. تماس‌ها از موجودی پلتفرم استفاده می‌کنند، نه اعتبارات Felo Pro. نمونه‌های پاسخ صرفاً نمایشی هستند؛ محتوای زنده و فیلدهای اختیاری متفاوت‌اند.

یک عملیات را انتخاب کنید

1. دریافت پروفایل‌های کاربر

POST /api/v1/data/x/user/info

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/info" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"usernames":["OpenAI"]}'

پاسخ شامل users و total است. هر کاربر شامل user_id، username و display_name است؛ متن پروفایل، تعداد دنبال‌کنندگان، تأییدشدگی و سایر فراداده‌ها نیز ممکن است موجود باشند. یک دسته می‌تواند پروفایل‌های کمتری از تعداد درخواستی برگرداند. تطبیق را بر اساس نام کاربری یا شناسه انجام دهید، نه بر اساس موقعیت در آرایه.

{"users":[{"user_id":"example-user-id","username":"example","display_name":"Example"}],"total":1}

2. جستجوی کاربران

POST /api/v1/data/x/user/search

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"AI research"}'

پاسخ شامل users، total، has_next و next_cursor است. برای این عملیات پارامتر limit وجود ندارد.

{"users":[],"total":0,"has_next":false,"next_cursor":null}

3. دریافت تایم‌لاین کاربر

POST /api/v1/data/x/user/tweets

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/user/tweets" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username":"OpenAI","limit":20,"include_replies":false}'

پاسخ شامل tweets، total، has_next و next_cursor است. تنظیم limit زیر 20 تضمین نمی‌کند که آیتم‌های بازگردانده‌شده کمتر باشند یا صورتحساب کوچک‌تر شود. شامل‌کردن پاسخ‌ها می‌تواند داده‌های بازگردانده‌شده و نتایج قابل‌صورتحساب را افزایش دهد.

محدودیت‌های نتیجه و پاسخ‌های تودرتو

limit تعداد هدف برای پست‌های سطح بالا در این درخواست است، نه تعداد نتیجه تضمین‌شده. پیاده‌سازی فعلی از هدفی حداقل 20 استفاده می‌کند: هدف 20 یک صفحه بالادستی را می‌خواند؛ اهداف بزرگ‌تر به‌طور خودکار تا 50 صفحه را واکشی می‌کنند. پیش از هر صفحه، زمان سپری‌شده بررسی می‌شود و وقتی از 60 ثانیه فراتر رود، واکشی صفحات بیشتر متوقف می‌شود. این بررسی تضمین نمی‌کند که کل درخواست HTTP در 60 ثانیه تمام شود.

گردآوری همچنین وقتی هدف برآورده شود، صفحه بعدی بالادست وجود نداشته باشد، یک صفحه خالی باشد، یا cursor موجود نباشد متوقف می‌شود. بنابراین یک پاسخ موفق ممکن است کمتر از limit پست داشته باشد. در صورت وجود، از has_next و next_cursor برای ادامه استفاده کنید.

با include_replies=true، هر پست بازگردانده‌شده تا 5 صفحه اضافی و حداکثر 100 پاسخ تودرتو دریافت می‌کند. گردآوری می‌تواند زودتر متوقف شود وقتی صفحه بعدی وجود نداشته باشد، صفحه‌ای خالی باشد، یا cursor نتواند پیش برود. این پاسخ‌های تودرتو خارج از limit و total سطح بالا هستند، اما می‌توانند نتایج قابل‌صورتحساب را افزایش دهند.

replies تودرتو یک بایگانی کامل پاسخ‌ها نیست و یک cursor ادامه‌دهنده جداگانه برای این گردآوری اضافی در اختیار نمی‌گذارد. برای صفحه‌بندی مستقل پاسخ‌ها، از عملیات Read replies و cursor بازگردانده‌شده آن استفاده کنید. از cursor پست سطح بالا برای پاسخ‌ها استفاده نکنید.

4. جستجوی پست‌ها

POST /api/v1/data/x/tweet/search

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/tweet/search" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"retrieval augmented generation","query_type":"Latest","limit":20}'

پاسخ شامل tweets، total، has_next و next_cursor است. اشیای پست شامل id، content، author، created_at و metrics هستند؛ پاسخ‌ها و پست‌های نقل‌قول‌شده/بازنشرشده ممکن است تودرتو باشند. شناسه‌ها را به‌صورت رشته در نظر بگیرید.

محدودیت‌های تعداد نتیجه

limit یک هدف است، نه تضمین. پیاده‌سازی فعلی از هدفی حداقل 20 استفاده می‌کند: هدف 20 یک صفحه بالادستی را می‌خواند؛ اهداف بزرگ‌تر به‌طور خودکار تا 50 صفحه را واکشی می‌کنند. زمان سپری‌شده پیش از هر صفحه بررسی می‌شود و پس از فراتر رفتن از 60 ثانیه، صفحه دیگری واکشی نمی‌شود. یک درخواست بالادستی در حال اجرا هنوز می‌تواند زمان ببرد، بنابراین این یک زمان‌اِتمام کلی HTTP نیست.

گردآوری همچنین وقتی هدف برآورده شود، صفحه بعدی بالادست وجود نداشته باشد، یک صفحه خالی باشد، یا cursor موجود نباشد متوقف می‌شود. بازگرداندن کمتر از limit پست به این معنا نیست که درخواست ناموفق بوده یا هر پست منطبق بازیابی شده است. پیش از ادامه، has_next و next_cursor را بررسی کنید.

{
  "tweets": [{
    "id":"example-post-id",
    "content":"Example post content",
    "author":{"user_id":"example-user-id","username":"example","display_name":"Example"},
    "created_at":"2026-11-01T00:00:00Z",
    "metrics":{},
    "replies":[]
  }],
  "total":1,
  "has_next":false,
  "next_cursor":null
}

5. خواندن پاسخ‌ها

POST /api/v1/data/x/tweet/replies

جای‌نگهدار را با یک شناسه واقعی پست جایگزین کنید:

curl -sS --request POST "https://openapi.felo.ai/api/v1/data/x/tweet/replies" \
  -H "Authorization: Bearer $FELO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tweet_ids":["POST_ID"]}'

برخلاف تایم‌لاین و جستجوی پست، پاسخ‌ها زیر results گروه‌بندی می‌شوند. هر ورودی وضعیت صفحه‌بندی خودش را دارد:

{"results":[{"tweet_id":"POST_ID","replies":[],"total":0,"has_next":false,"next_cursor":null}]}

محدودیت‌های پاسخ در هر درخواست

هر درخواست یک صفحه پاسخ بالادستی را به ازای هر tweet_id می‌خواند و حداکثر 100 پاسخ را نگه می‌دارد؛ این کار به‌طور خودکار همه صفحات پاسخ را واکشی نمی‌کند. در یک دسته تا 20 شناسه، سقف 100-پاسخی به‌طور جداگانه برای هر ورودی results اعمال می‌شود. شمارش واقعی می‌تواند کمتر باشد.

total هر ورودی تعداد پاسخ‌های بازگردانده‌شده در همان ورودی است، نه تعداد کامل پاسخ‌های آن پست. برای ادامه، از next_cursor همان ورودی استفاده کنید و در درخواست بعدی فقط همان شناسه یکتا پست را ارسال کنید. برای افزایش سقف هر درخواست پارامتر limit وجود ندارد.

صفحه‌بندی و کنترل هزینه

total آرایه متناظر را در پاسخ فعلی می‌شمارد: پست‌های سطح بالا برای پرس‌وجوهای پست، یا پاسخ‌ها درون هر ورودی نتیجه برای پرس‌وجوهای پاسخ. این یک شمارش جهانیِ تطابق‌ها، تعداد کامل پاسخ‌های یک پست، یا شمارش نهایی قابل‌صورتحساب نیست.

1. درخواست اول را بدون cursor بفرستید.
2. has_next و next_cursor را از پاسخ بخوانید. برای پاسخ‌ها، آن‌ها را روی هر ورودی نتیجه بخوانید.
3. اگر صفحه دیگری وجود دارد و cursor خالی نیست، همان را بدون تغییر با همان پرس‌وجو بفرستید. برای یک دسته پاسخ، هر پست را جداگانه ادامه دهید.
4. وقتی صفحه بعدی وجود ندارد، وقتی cursor تکرار می‌شود، یا وقتی سقف صفحه یا هزینه خودتان به پایان می‌رسد، متوقف شوید.

فراداده صفحه‌بندی نشان‌دهنده آخرین پاسخ بالادستی است؛ مجموعه بازگردانده‌شده می‌تواند در یک سقف نتیجه کوتاه شود. حتی has_next=false نیز تضمین نمی‌کند که تمام تاریخچه X یا پاسخ‌ها بازیابی شده‌اند. به‌جای برچسب‌زدن یک مجموعه نتیجه محدود به‌عنوان همه داده‌های موجود، شمارش واقعی بازگردانده‌شده را نمایش دهید.

هر صفحه موفق می‌تواند هزینه‌ای در پی داشته باشد. این پنج عملیات بر اساس نتایج بازگردانده‌شده صورتحساب می‌شوند، نه یک هزینه ثابت برای هر درخواست. پاسخ‌های تودرتو و سایر رکوردهای بازگردانده‌شده می‌توانند روی شمارش صورتحساب اثر بگذارند؛ هزینه را فقط بر اساس طول آرایه سطح بالا تخمین نزنید. قیمت‌های فعلی و استفاده در کنسول را بررسی کنید. فیلدهای کامل شیء در اسکیما OpenAPI موجود است.