# Locates

## List Locate Rates

**get** `/v1/locates/rates`

> **Beta** — this endpoint may change before general availability.

Fetch the cached locate borrow rates for up to 1,000 instruments. The
response returns one row per requested instrument, in request order. Each
row carries either the `rate` or an `error` — a `404` when the instrument
is unknown or has no cached rate. The status is `207` when any row has an
error, `200` when every instrument resolved to a rate.

### Query Parameters

- `instrument_ids: array of InstrumentIDOrSymbol`

  Comma-separated instrument IDs (UUID) or symbols; at least one, at most 1,000.

### Returns

- `data: LocateRateResultList`

  - `instrument: InstrumentIDOrSymbol`

    The instrument id (UUID) or symbol, echoed exactly as requested, so each
    result maps back to its request.

  - `error: optional APIError`

    Why no rate is present — a `404` when the instrument is unknown or has
    no cached rate. Omitted when `rate` is present.

    - `code: number`

      The error code is used to identify the nature of the error. It corresponds
      to an HTTP status code.

    - `message: string`

      A human-readable message providing more details about the error.

    - `details: optional array of map[unknown]`

      Additional error details, if any. This can include structured information
      such as field violations or error metadata.

  - `rate: optional LocateRate`

    The cached borrow rate. Present when a rate was found; omitted when
    `error` is present.

    - `instrument_id: string`

      Instrument id the rate applies to.

    - `rate: string`

      Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%).

    - `as_of: optional string`

      When the rate was requested from the locates venue.

### Example

```http
curl https://api.clearstreet.com/v1/locates/rates \
    -H "Authorization: Bearer $API_KEY"
```

#### Response

```json
{
  "metadata": {
    "request_id": "request_id",
    "next_page_token": "U3RhaW5sZXNzIHJvY2tz",
    "page_number": 1,
    "previous_page_token": "U3RhaW5sZXNzIHJvY2tz",
    "total_items": 42,
    "total_pages": 5
  },
  "error": {
    "code": 400,
    "message": "Order quantity must be greater than zero",
    "details": [
      {
        "foo": "bar"
      }
    ]
  },
  "data": [
    {
      "instrument": "AAPL",
      "error": {
        "code": 400,
        "message": "Order quantity must be greater than zero",
        "details": [
          {
            "foo": "bar"
          }
        ]
      },
      "rate": {
        "instrument_id": "528ec5c3-cdbf-447c-b995-ec6c83cfbc02",
        "rate": "0.037012",
        "as_of": "2026-09-10T14:33:07.107683Z"
      }
    }
  ]
}
```

## Get Locate Rate

**get** `/v1/locates/rates/{instrument_id}`

> **Beta** — this endpoint may change before general availability.

Fetch the cached locate borrow rate for one instrument. Rates refresh
periodically; `404` means no rate is currently cached for the instrument.

### Path Parameters

- `instrument_id: InstrumentIDOrSymbol`

  Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side.

### Returns

- `data: LocateRate`

  A locate borrow rate for an instrument.

  - `instrument_id: string`

    Instrument id the rate applies to.

  - `rate: string`

    Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%).

  - `as_of: optional string`

    When the rate was requested from the locates venue.

### Example

```http
curl https://api.clearstreet.com/v1/locates/rates/$INSTRUMENT_ID \
    -H "Authorization: Bearer $API_KEY"
```

#### Response

```json
{
  "metadata": {
    "request_id": "request_id",
    "next_page_token": "U3RhaW5sZXNzIHJvY2tz",
    "page_number": 1,
    "previous_page_token": "U3RhaW5sZXNzIHJvY2tz",
    "total_items": 42,
    "total_pages": 5
  },
  "error": {
    "code": 400,
    "message": "Order quantity must be greater than zero",
    "details": [
      {
        "foo": "bar"
      }
    ]
  },
  "data": {
    "instrument_id": "528ec5c3-cdbf-447c-b995-ec6c83cfbc02",
    "rate": "0.037012",
    "as_of": "2026-09-10T14:33:07.107683Z"
  }
}
```

## List Locates

**get** `/v1/accounts/{account_id}/locates`

> **Beta** — this endpoint may change before general availability.

List locates for the account on one effective date, which defaults to today's
New York calendar date. Filter by comma-separated statuses and instrument ids or symbols.

### Path Parameters

- `account_id: number`

### Query Parameters

- `effective_date: optional string`

  Effective date to list; defaults to today's New York calendar date. Explicit dates are used unchanged, including weekends and holidays.

- `instrument_ids: optional array of InstrumentIDOrSymbol`

  Comma-separated instrument IDs (UUID) or symbols.

- `status: optional array of "REQUESTED" or "ACCEPTED" or "REJECTED" or "EXPIRED"`

  Comma-separated locate statuses to filter by

  - `"REQUESTED"`

  - `"ACCEPTED"`

  - `"REJECTED"`

  - `"EXPIRED"`

### Returns

- `data: LocateList`

  - `account_id: number`

    Account the locate is booked to.

  - `client_request_id: string`

    Caller-assigned id of the locate request.

  - `effective_date: string`

    New York calendar date the locate is in force for.

  - `instrument_id: string`

    Instrument id.

  - `locate_request_id: string`

    Engine-assigned locate request id.

  - `requested_quantity: number`

    Number of shares requested.

  - `status: LocateStatus`

    Presented status of the locate.

    - `"REQUESTED"`

    - `"ACCEPTED"`

    - `"REJECTED"`

    - `"EXPIRED"`

  - `locate_id: optional string`

    Engine-assigned locate id; set once the locate is granted.
    When a null/undefined value is observed, it indicates it does not apply.

  - `quantity: optional number`

    Number of shares granted; set once the locate is granted.
    When a null/undefined value is observed, it indicates it does not apply.

  - `related_order_id: optional string`

    Client order id the request relates to, if any.
    When a null/undefined value is observed, it indicates it does not apply.

  - `reserved_quantity: optional number`

    Number of granted shares reserved.
    When a null/undefined value is observed, it indicates it does not apply.

  - `used_quantity: optional number`

    Number of granted shares already used.
    When a null/undefined value is observed, it indicates it does not apply.

### Example

```http
curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/locates \
    -H "Authorization: Bearer $API_KEY"
```

#### Response

```json
{
  "metadata": {
    "request_id": "request_id",
    "next_page_token": "U3RhaW5sZXNzIHJvY2tz",
    "page_number": 1,
    "previous_page_token": "U3RhaW5sZXNzIHJvY2tz",
    "total_items": 42,
    "total_pages": 5
  },
  "error": {
    "code": 400,
    "message": "Order quantity must be greater than zero",
    "details": [
      {
        "foo": "bar"
      }
    ]
  },
  "data": [
    {
      "account_id": 0,
      "client_request_id": "client_request_id",
      "effective_date": "2019-12-27",
      "instrument_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "locate_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "requested_quantity": 0,
      "status": "REQUESTED",
      "locate_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "quantity": 0,
      "related_order_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "reserved_quantity": 0,
      "used_quantity": 0
    }
  ]
}
```

## Get Locate

**get** `/v1/accounts/{account_id}/locates/{id}`

> **Beta** — this endpoint may change before general availability.

Fetch one locate by id, matched against the locate request id, locate id,
and client request id, across all days in force.

### Path Parameters

- `account_id: number`

- `id: string`

### Returns

- `data: Locate`

  A locate request joined with the locate granted for it, if any.

  - `account_id: number`

    Account the locate is booked to.

  - `client_request_id: string`

    Caller-assigned id of the locate request.

  - `effective_date: string`

    New York calendar date the locate is in force for.

  - `instrument_id: string`

    Instrument id.

  - `locate_request_id: string`

    Engine-assigned locate request id.

  - `requested_quantity: number`

    Number of shares requested.

  - `status: LocateStatus`

    Presented status of the locate.

    - `"REQUESTED"`

    - `"ACCEPTED"`

    - `"REJECTED"`

    - `"EXPIRED"`

  - `locate_id: optional string`

    Engine-assigned locate id; set once the locate is granted.
    When a null/undefined value is observed, it indicates it does not apply.

  - `quantity: optional number`

    Number of shares granted; set once the locate is granted.
    When a null/undefined value is observed, it indicates it does not apply.

  - `related_order_id: optional string`

    Client order id the request relates to, if any.
    When a null/undefined value is observed, it indicates it does not apply.

  - `reserved_quantity: optional number`

    Number of granted shares reserved.
    When a null/undefined value is observed, it indicates it does not apply.

  - `used_quantity: optional number`

    Number of granted shares already used.
    When a null/undefined value is observed, it indicates it does not apply.

### Example

```http
curl https://api.clearstreet.com/v1/accounts/$ACCOUNT_ID/locates/$ID \
    -H "Authorization: Bearer $API_KEY"
```

#### Response

```json
{
  "metadata": {
    "request_id": "request_id",
    "next_page_token": "U3RhaW5sZXNzIHJvY2tz",
    "page_number": 1,
    "previous_page_token": "U3RhaW5sZXNzIHJvY2tz",
    "total_items": 42,
    "total_pages": 5
  },
  "error": {
    "code": 400,
    "message": "Order quantity must be greater than zero",
    "details": [
      {
        "foo": "bar"
      }
    ]
  },
  "data": {
    "account_id": 0,
    "client_request_id": "client_request_id",
    "effective_date": "2019-12-27",
    "instrument_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "locate_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "requested_quantity": 0,
    "status": "REQUESTED",
    "locate_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "quantity": 0,
    "related_order_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "reserved_quantity": 0,
    "used_quantity": 0
  }
}
```

## Domain Types

### Locate

- `Locate object { account_id, client_request_id, effective_date, 9 more }`

  A locate request joined with the locate granted for it, if any.

  - `account_id: number`

    Account the locate is booked to.

  - `client_request_id: string`

    Caller-assigned id of the locate request.

  - `effective_date: string`

    New York calendar date the locate is in force for.

  - `instrument_id: string`

    Instrument id.

  - `locate_request_id: string`

    Engine-assigned locate request id.

  - `requested_quantity: number`

    Number of shares requested.

  - `status: LocateStatus`

    Presented status of the locate.

    - `"REQUESTED"`

    - `"ACCEPTED"`

    - `"REJECTED"`

    - `"EXPIRED"`

  - `locate_id: optional string`

    Engine-assigned locate id; set once the locate is granted.
    When a null/undefined value is observed, it indicates it does not apply.

  - `quantity: optional number`

    Number of shares granted; set once the locate is granted.
    When a null/undefined value is observed, it indicates it does not apply.

  - `related_order_id: optional string`

    Client order id the request relates to, if any.
    When a null/undefined value is observed, it indicates it does not apply.

  - `reserved_quantity: optional number`

    Number of granted shares reserved.
    When a null/undefined value is observed, it indicates it does not apply.

  - `used_quantity: optional number`

    Number of granted shares already used.
    When a null/undefined value is observed, it indicates it does not apply.

### Locate List

- `LocateList = array of Locate`

  - `account_id: number`

    Account the locate is booked to.

  - `client_request_id: string`

    Caller-assigned id of the locate request.

  - `effective_date: string`

    New York calendar date the locate is in force for.

  - `instrument_id: string`

    Instrument id.

  - `locate_request_id: string`

    Engine-assigned locate request id.

  - `requested_quantity: number`

    Number of shares requested.

  - `status: LocateStatus`

    Presented status of the locate.

    - `"REQUESTED"`

    - `"ACCEPTED"`

    - `"REJECTED"`

    - `"EXPIRED"`

  - `locate_id: optional string`

    Engine-assigned locate id; set once the locate is granted.
    When a null/undefined value is observed, it indicates it does not apply.

  - `quantity: optional number`

    Number of shares granted; set once the locate is granted.
    When a null/undefined value is observed, it indicates it does not apply.

  - `related_order_id: optional string`

    Client order id the request relates to, if any.
    When a null/undefined value is observed, it indicates it does not apply.

  - `reserved_quantity: optional number`

    Number of granted shares reserved.
    When a null/undefined value is observed, it indicates it does not apply.

  - `used_quantity: optional number`

    Number of granted shares already used.
    When a null/undefined value is observed, it indicates it does not apply.

### Locate Rate

- `LocateRate object { instrument_id, rate, as_of }`

  A locate borrow rate for an instrument.

  - `instrument_id: string`

    Instrument id the rate applies to.

  - `rate: string`

    Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%).

  - `as_of: optional string`

    When the rate was requested from the locates venue.

### Locate Rate Result

- `LocateRateResult object { instrument, error, rate }`

  A requested instrument with either its cached borrow rate or an error.

  - `instrument: InstrumentIDOrSymbol`

    The instrument id (UUID) or symbol, echoed exactly as requested, so each
    result maps back to its request.

  - `error: optional APIError`

    Why no rate is present — a `404` when the instrument is unknown or has
    no cached rate. Omitted when `rate` is present.

    - `code: number`

      The error code is used to identify the nature of the error. It corresponds
      to an HTTP status code.

    - `message: string`

      A human-readable message providing more details about the error.

    - `details: optional array of map[unknown]`

      Additional error details, if any. This can include structured information
      such as field violations or error metadata.

  - `rate: optional LocateRate`

    The cached borrow rate. Present when a rate was found; omitted when
    `error` is present.

    - `instrument_id: string`

      Instrument id the rate applies to.

    - `rate: string`

      Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%).

    - `as_of: optional string`

      When the rate was requested from the locates venue.

### Locate Rate Result List

- `LocateRateResultList = array of LocateRateResult`

  - `instrument: InstrumentIDOrSymbol`

    The instrument id (UUID) or symbol, echoed exactly as requested, so each
    result maps back to its request.

  - `error: optional APIError`

    Why no rate is present — a `404` when the instrument is unknown or has
    no cached rate. Omitted when `rate` is present.

    - `code: number`

      The error code is used to identify the nature of the error. It corresponds
      to an HTTP status code.

    - `message: string`

      A human-readable message providing more details about the error.

    - `details: optional array of map[unknown]`

      Additional error details, if any. This can include structured information
      such as field violations or error metadata.

  - `rate: optional LocateRate`

    The cached borrow rate. Present when a rate was found; omitted when
    `error` is present.

    - `instrument_id: string`

      Instrument id the rate applies to.

    - `rate: string`

      Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%).

    - `as_of: optional string`

      When the rate was requested from the locates venue.

### Locate Status

- `LocateStatus = "REQUESTED" or "ACCEPTED" or "REJECTED" or "EXPIRED"`

  The presented status of a locate: the locate-request lifecycle plus
  `EXPIRED` for accepted locates whose effective date has passed.

  - `"REQUESTED"`

  - `"ACCEPTED"`

  - `"REJECTED"`

  - `"EXPIRED"`

### Locate Get Locate Rates Response

- `LocateGetLocateRatesResponse = BaseResponse`

  - `data: LocateRateResultList`

    - `instrument: InstrumentIDOrSymbol`

      The instrument id (UUID) or symbol, echoed exactly as requested, so each
      result maps back to its request.

    - `error: optional APIError`

      Why no rate is present — a `404` when the instrument is unknown or has
      no cached rate. Omitted when `rate` is present.

      - `code: number`

        The error code is used to identify the nature of the error. It corresponds
        to an HTTP status code.

      - `message: string`

        A human-readable message providing more details about the error.

      - `details: optional array of map[unknown]`

        Additional error details, if any. This can include structured information
        such as field violations or error metadata.

    - `rate: optional LocateRate`

      The cached borrow rate. Present when a rate was found; omitted when
      `error` is present.

      - `instrument_id: string`

        Instrument id the rate applies to.

      - `rate: string`

        Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%).

      - `as_of: optional string`

        When the rate was requested from the locates venue.

### Locate Get Locate Rate By ID Response

- `LocateGetLocateRateByIDResponse = BaseResponse`

  - `data: LocateRate`

    A locate borrow rate for an instrument.

    - `instrument_id: string`

      Instrument id the rate applies to.

    - `rate: string`

      Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%).

    - `as_of: optional string`

      When the rate was requested from the locates venue.

### Locate Get Locates Response

- `LocateGetLocatesResponse = BaseResponse`

  - `data: LocateList`

    - `account_id: number`

      Account the locate is booked to.

    - `client_request_id: string`

      Caller-assigned id of the locate request.

    - `effective_date: string`

      New York calendar date the locate is in force for.

    - `instrument_id: string`

      Instrument id.

    - `locate_request_id: string`

      Engine-assigned locate request id.

    - `requested_quantity: number`

      Number of shares requested.

    - `status: LocateStatus`

      Presented status of the locate.

      - `"REQUESTED"`

      - `"ACCEPTED"`

      - `"REJECTED"`

      - `"EXPIRED"`

    - `locate_id: optional string`

      Engine-assigned locate id; set once the locate is granted.
      When a null/undefined value is observed, it indicates it does not apply.

    - `quantity: optional number`

      Number of shares granted; set once the locate is granted.
      When a null/undefined value is observed, it indicates it does not apply.

    - `related_order_id: optional string`

      Client order id the request relates to, if any.
      When a null/undefined value is observed, it indicates it does not apply.

    - `reserved_quantity: optional number`

      Number of granted shares reserved.
      When a null/undefined value is observed, it indicates it does not apply.

    - `used_quantity: optional number`

      Number of granted shares already used.
      When a null/undefined value is observed, it indicates it does not apply.

### Locate Get Locate By ID Response

- `LocateGetLocateByIDResponse = BaseResponse`

  - `data: Locate`

    A locate request joined with the locate granted for it, if any.

    - `account_id: number`

      Account the locate is booked to.

    - `client_request_id: string`

      Caller-assigned id of the locate request.

    - `effective_date: string`

      New York calendar date the locate is in force for.

    - `instrument_id: string`

      Instrument id.

    - `locate_request_id: string`

      Engine-assigned locate request id.

    - `requested_quantity: number`

      Number of shares requested.

    - `status: LocateStatus`

      Presented status of the locate.

      - `"REQUESTED"`

      - `"ACCEPTED"`

      - `"REJECTED"`

      - `"EXPIRED"`

    - `locate_id: optional string`

      Engine-assigned locate id; set once the locate is granted.
      When a null/undefined value is observed, it indicates it does not apply.

    - `quantity: optional number`

      Number of shares granted; set once the locate is granted.
      When a null/undefined value is observed, it indicates it does not apply.

    - `related_order_id: optional string`

      Client order id the request relates to, if any.
      When a null/undefined value is observed, it indicates it does not apply.

    - `reserved_quantity: optional number`

      Number of granted shares reserved.
      When a null/undefined value is observed, it indicates it does not apply.

    - `used_quantity: optional number`

      Number of granted shares already used.
      When a null/undefined value is observed, it indicates it does not apply.