> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arrays.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Track (discover) an X handle

> [OpenAPI JSON Spec](/docs/output/v1_social-feeds_x_handles_post.json)
Explicitly start tracking a Twitter handle. Unknown handles are
resolved on X and a subscription is created; dormant handles are
revived. Returns the first page of tweets and an "outcome".
This is the ONLY endpoint that triggers on-demand X fetching; it is
per-user rate-capped and billed as a premium "discovery" unit.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/social-feeds/x/handles
openapi: 3.0.0
info:
  contact: {}
  description: >-
    Welcome to Arrays!


    Arrays is a unified financial data layer for both financial institutions and
    retail users, delivering comprehensive market data across crypto and equity
    markets. Our datasets cover fundamentals, ETFs, options, crypto, and more.


    Visit [arrays.org](https://arrays.org) to request an API key and start your
    free trial. You can explore our full API offerings in the documentation
    below.


    For any questions regarding APIs or pricing, please contact
    support@arrays.org.
  title: Arrays API
  version: '1.0'
servers:
  - url: https://data-tools.prd.arrays.org/api
security: []
paths:
  /v1/social-feeds/x/handles:
    post:
      tags:
        - x-feed
      summary: Track (discover) an X handle
      description: |-
        [OpenAPI JSON Spec](/docs/output/v1_social-feeds_x_handles_post.json)
        Explicitly start tracking a Twitter handle. Unknown handles are
        resolved on X and a subscription is created; dormant handles are
        revived. Returns the first page of tweets and an "outcome".
        This is the ONLY endpoint that triggers on-demand X fetching; it is
        per-user rate-capped and billed as a premium "discovery" unit.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/model.DiscoverXFeedHandleRequest'
        description: Handle to discover
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/model.APIResponse'
                  - properties:
                      data:
                        items:
                          $ref: '#/components/schemas/model.XFeedTweet'
                        type: array
                    type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/model.APIResponse'
                  - properties:
                      data:
                        $ref: '#/components/schemas/model.APIError'
                    type: object
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/model.APIResponse'
                  - properties:
                      data:
                        $ref: '#/components/schemas/model.APIError'
                    type: object
      security:
        - ApiKeyAuth: []
components:
  schemas:
    model.DiscoverXFeedHandleRequest:
      properties:
        handle:
          example: elonmusk
          type: string
      required:
        - handle
      type: object
    model.APIResponse:
      properties:
        data: {}
        error:
          $ref: '#/components/schemas/model.APIError'
        pagination: {}
        request_id:
          type: string
        success:
          type: boolean
      type: object
    model.XFeedTweet:
      properties:
        bookmark_count:
          example: 34
          type: integer
        content_type:
          example: original
          type: string
        conversation_id:
          example: '1799123456789'
          type: string
        display_name:
          example: Cathie Wood
          type: string
        entity_mentions:
          allOf:
            - $ref: '#/components/schemas/model.XFeedEntityMentions'
          description: EntityMentions：MVP 永远为空对象 / 空数组（PRD D7-13）；保留字段供 V2 填充。
        first_observed_at:
          example: '2025-04-25T12:00:00Z'
          type: string
        full_text:
          example: Disruptive innovation will continue.
          type: string
        hashtags:
          example:
            - AI
            - ETF
          items:
            type: string
          type: array
        in_reply_to_user_id:
          example: '44196397'
          type: string
        last_edited_at:
          example: '2025-04-25T12:40:00Z'
          type: string
        last_observed_at:
          example: '2025-04-25T12:40:00Z'
          type: string
        like_count:
          example: 1234
          type: integer
        media:
          items:
            $ref: '#/components/schemas/model.XFeedMedia'
          type: array
        media_json:
          type: string
        mentions:
          example:
            - elonmusk
          items:
            type: string
          type: array
        meta_json:
          description: |-
            MetaJSON / MediaJSON 透传 JSONB；客户端按需自行解析。
            Media 是 MediaJSON 解析后的结构化版本，便于直接消费。
          type: string
        platform_id:
          example: '1799123456789'
          type: string
        published_at:
          example: '2025-04-25T12:34:56Z'
          type: string
        quote_count:
          description: >-
            Extended engagement + threading fields (Task 7).

            Pointer types parallel to the four counters above — nil means
            missing /

            unknown, &0 is a real zero. With value-type int64 + omitempty, the
            JSON

            encoder silently dropped genuine 0 values.
          example: 12
          type: integer
        referenced_tweet_id:
          description: >-
            Deprecated: use ReferencedTweets instead. Equals
            ReferencedTweets[0].ID /

            ReferencedTweets[0].Type for backward compat with arrays-skills
            v1.1.0 and

            earlier. Multi-ref tweets only expose the first ref here (X API
            ordering);

            use ReferencedTweets[] for the full picture. Will be removed in PR-b

            (~1 week after PR-a stabilizes, once arrays-skills v1.2+ no longer

            references these fields).
          example: '1799000000001'
          type: string
        referenced_tweet_type:
          example: quoted
          type: string
        referenced_tweets:
          description: |-
            ReferencedTweets replaces the legacy referenced_tweet_id/type pair.
            X API v2 allows a single tweet to reference multiple others.
          items:
            $ref: '#/components/schemas/model.TweetReference'
          type: array
        reply_count:
          example: 78
          type: integer
        retweet_count:
          example: 56
          type: integer
        source:
          allOf:
            - $ref: '#/components/schemas/model.XFeedTweet'
          description: >-
            Source is the nested source tweet for retweet/quote/reply. Always
            nil

            for content_type="original". Handler-hydrated via batch lookup in

            hydrateSources (see Task 14). Source.Source is naturally nil — the

            gRPC server doesn't populate it and we don't recurse hydration.
        twitter_handle:
          example: CathieDWood
          type: string
        url:
          example: https://x.com/CathieDWood/status/1799123456789
          type: string
        view_count:
          example: 90000
          type: integer
      type: object
    model.APIError:
      properties:
        code:
          example: RESOURCE_NOT_FOUND
          type: string
        details:
          items:
            $ref: '#/components/schemas/model.APIErrorDetail'
          type: array
        docs_url:
          type: string
        examples:
          items:
            type: string
          type: array
        hint:
          type: string
        message:
          example: The requested resource was not found.
          type: string
        suggestions:
          items:
            type: string
          type: array
      type: object
    model.XFeedEntityMentions:
      properties:
        people:
          items:
            $ref: '#/components/schemas/model.XFeedPersonMention'
          type: array
        tickers:
          items:
            $ref: '#/components/schemas/model.XFeedTickerMention'
          type: array
        topics:
          items:
            $ref: '#/components/schemas/model.XFeedTopicMention'
          type: array
      type: object
    model.XFeedMedia:
      properties:
        alt_text:
          type: string
        duration_ms:
          example: 15000
          type: integer
        height:
          example: 800
          type: integer
        media_key:
          example: '3_1234'
          type: string
        preview_image_url:
          type: string
        type:
          example: photo
          type: string
        url:
          example: https://pbs.twimg.com/media/foo.jpg
          type: string
        variants:
          items:
            $ref: '#/components/schemas/model.XFeedMediaVariant'
          type: array
        width:
          example: 1200
          type: integer
      type: object
    model.TweetReference:
      properties:
        author_display_name:
          example: Elon Musk
          type: string
        author_external_id:
          description: >-
            AuthorExternalID is the twitter_id of the referenced tweet's author,

            captured at ingestion time from X API's includes.tweets[]. Empty
            when

            unknown (legacy rows pre-backfill). The handler uses it to enable a

            PK-prefix fast path inside hydrateSources.
          example: '44196397'
          type: string
        author_handle:
          example: elonmusk
          type: string
        id:
          example: '1799000000001'
          type: string
        published_at:
          example: '2025-04-25T12:34:56Z'
          type: string
        text:
          type: string
        type:
          description: '"retweeted" | "quoted" | "replied_to"'
          example: quoted
          type: string
      type: object
    model.APIErrorDetail:
      properties:
        field:
          type: string
        got:
          type: string
        reason:
          type: string
      type: object
    model.XFeedPersonMention:
      properties:
        confidence:
          type: number
        mention_method:
          type: string
        person_id:
          type: integer
      type: object
    model.XFeedTickerMention:
      properties:
        confidence:
          type: number
        mention_method:
          type: string
        ticker:
          type: string
      type: object
    model.XFeedTopicMention:
      properties:
        matched_keywords:
          items:
            type: string
          type: array
        topic_id:
          type: string
      type: object
    model.XFeedMediaVariant:
      properties:
        bit_rate:
          type: integer
        content_type:
          example: video/mp4
          type: string
        url:
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: 'API Key authentication. Example: "your-api-key-here"'
      in: header
      name: X-API-Key
      type: apiKey

````