Alphanume Short Locates API

openapi: 3.2.0
info:
  contact:
    url: https://alphanume.com
  description: 'Point-in-time, survivorship-aware datasets for US equities and options research. Every response is JSON: {"count": N, "data": [...]} (paginated endpoints add has_more and next_cursor). Dates are always YYYY-MM-DD. Access: every dataset requires an Alphanume Pro API key (the Free plan is retired as of September 6, 2026). A 403 error with code PRO_SUBSCRIPTION_REQUIRED or DATE_RANGE_RESTRICTED means the key''s plan does not cover the request -- it does not mean the data is missing. Authentication: send your API key in the X-API-Key header (or Authorization: Bearer). Rate limit: 600 requests/minute. Keys come with a Pro subscription at https://alphanume.com/pricing. The same datasets are available as MCP tools at https://mcp.alphanume.com/mcp.'
  title: Alphanume Short Locates API
  version: 1.1.0
servers:
- url: https://api.alphanume.com
security:
- ApiKeyHeader: []
- BearerKey: []
tags:
- name: Short Locates
paths:
  /v1/short-locates:
    get:
      description: 'Short-locate costs: what it costs to locate (borrow for shorting) shares of every

        hard-to-borrow US stock, observed twice a day -- point-in-time, never revised.


        One row per (date, slot, ticker). Each sweep prices every listed US stock the broker

        marks NOT easy-to-borrow (~7,500 names). Served per row: date (US/Eastern trading

        date of the sweep), slot (am / pm), snapshot_time_utc (when the sweep ran, UTC to

        the minute, e.g. ''2026-10-15 11:45'' -- every row of a sweep shares it), ticker, status, price_per_share (USD per share),

        cost_per_100 (USD to locate 100 shares) and available_qty (shares that can be

        located right now). price_per_share and cost_per_100 are NULL unless status is

        ''offered''; available_qty is NULL unless a quote came back (0 for ''no_shares'').


        Typical uses: the borrow cost of a short idea on a given morning, names whose

        locate cost spiked or whose availability dried up, threshold-list membership over

        time, and the cost side of a short-selling backtest from 2026-10-08 onward.


        Requires an Alphanume Pro API key. There is no date clamp on this route.


        Honest limits, stated plainly. These are one broker''s (Alpaca''s) locate quotes for

        its own inventory, not a market-wide borrow rate -- another broker can quote the same

        name 2x higher or lower. Names the broker lends freely (easy-to-borrow) are not in

        the dataset. History starts 2026-10-08 and there is no backfill: locate quotes only

        exist live. Two sweeps a day, so intraday moves between sweeps are not captured.


        Default order: newest date first, pm before am, then ticker, so the first page is the

        latest sweep. One sweep is ~7,500 rows: filter by ticker, date, slot or status to keep

        results small.


        Pagination: results are capped at 50,000 rows per request; when the response has

        has_more=true, pass next_cursor''s cursor_date, cursor_slot and cursor_ticker back to

        fetch the next page.'
      operationId: get_short_locates
      parameters:
      - description: Ticker symbol filter, e.g. 'AAPL'. Case-insensitive.
        in: query
        name: ticker
        required: false
        schema:
          type: string
      - description: Exact date, YYYY-MM-DD. Cannot be combined with the date range parameters.
        in: query
        name: date
        required: false
        schema:
          type: string
      - description: Start of date range, inclusive (YYYY-MM-DD).
        in: query
        name: date_gte
        required: false
        schema:
          type: string
      - description: End of date range, inclusive (YYYY-MM-DD).
        in: query
        name: date_lte
        required: false
        schema:
          type: string
      - description: Start of date range, exclusive (YYYY-MM-DD).
        in: query
        name: date_gt
        required: false
        schema:
          type: string
      - description: End of date range, exclusive (YYYY-MM-DD).
        in: query
        name: date_lt
        required: false
        schema:
          type: string
      - description: 'Which daily sweep: ''am'' (11:45 UTC; 07:45 ET in summer, 06:45 ET in winter) or ''pm'' (17:30 UTC; 13:30 ET in summer, 12:30 ET in winter).'
        in: query
        name: slot
        required: false
        schema:
          enum:
          - am
          - pm
          type: string
      - description: 'What the broker answered: ''offered'' (shares can be located; price and availability set); ''no_shares'' (none available right now); ''threshold'' (on the Reg SHO threshold list, cannot be located); ''unavailable'' (no quote); ''corporate_action'' (cannot be quoted due to a corporate action); ''error'' (other refusal).'
        in: query
        name: status
        required: false
        schema:
          enum:
          - offered
          - no_shares
          - threshold
          - unavailable
          - corporate_action
          - error
          type: string
      - description: Only rows whose cost to locate 100 shares is at least this many US dollars (e.g. 5 for $5 per 100 shares). Unpriced rows are excluded whenever this is set.
        in: query
        name: min_cost_per_100
        required: false
        schema:
          type: number
      - description: 'Pagination: the ''cursor_date'' value from the previous response''s next_cursor. Send with cursor_slot and cursor_ticker.'
        in: query
        name: cursor_date
        required: false
        schema:
          type: string
      - description: 'Pagination: the ''cursor_slot'' value from the previous response''s next_cursor.'
        in: query
        name: cursor_slot
        required: false
        schema:
          enum:
          - am
          - pm
          type: string
      - description: 'Pagination: the ''cursor_ticker'' value from the previous response''s next_cursor.'
        in: query
        name: cursor_ticker
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEnvelope'
          description: Matching rows.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ProSubscriptionRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
      summary: 'Short-locate costs: what it costs to locate (borrow for shorting) shares of…'
      tags:
      - Short Locates
components:
  schemas:
    PaginatedEnvelope:
      properties:
        count:
          type: integer
        data:
          items:
            type: object
          type: array
        has_more:
          type: boolean
        next_cursor:
          description: 'Keyset cursor: pass its fields back as the cursor_* query parameters to fetch the next page.'
          type:
          - object
          - 'null'
      required:
      - count
      - data
      - has_more
      - next_cursor
      type: object
    Error:
      additionalProperties: true
      properties:
        error: {}
      type: object
  responses:
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Missing or unrecognized API key.
    ProSubscriptionRequired:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: 'PRO_SUBSCRIPTION_REQUIRED: the key''s plan does not include API access (every endpoint requires an active Pro subscription), or this Pro-only dataset is not covered by the key. No choice of dates makes the request succeed. The data is not missing.'
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Invalid or conflicting query parameters.
    RateLimited:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Rate limit exceeded (600/min); the body carries retry_after_seconds.
  securitySchemes:
    ApiKeyHeader:
      in: header
      name: X-API-Key
      type: apiKey
    BearerKey:
      scheme: bearer
      type: http
externalDocs:
  description: MCP server exposing these datasets as tools (OAuth or X-API-Key).
  url: https://mcp.alphanume.com/mcp