# Locates ## List Locate Rates `v1.locates.get_locate_rates(LocateGetLocateRatesParams**kwargs) -> LocateGetLocateRatesResponse` **get** `/v1/locates/rates` 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. ### Parameters - `instrument_ids: Sequence[InstrumentIDOrSymbol]` Comma-separated instrument IDs (UUID) or symbols; at least one, at most 1,000. ### Returns - `class LocateGetLocateRatesResponse: …` - `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: int` The error code is used to identify the nature of the error. It corresponds to an HTTP status code. - `message: str` A human-readable message providing more details about the error. - `details: Optional[List[Dict[str, object]]]` 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: str` Instrument id the rate applies to. - `rate: str` Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%). - `as_of: Optional[datetime]` When the rate was requested from the locates venue. ### Example ```python from clearstreet import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.locates.get_locate_rates( instrument_ids=["x"], ) print(response) ``` #### 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 `v1.locates.get_locate_rate_by_id(InstrumentIDOrSymbolinstrument_id) -> LocateGetLocateRateByIDResponse` **get** `/v1/locates/rates/{instrument_id}` Fetch the cached locate borrow rate for one instrument. Rates refresh periodically; `404` means no rate is currently cached for the instrument. ### 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 - `class LocateGetLocateRateByIDResponse: …` - `data: LocateRate` A locate borrow rate for an instrument. - `instrument_id: str` Instrument id the rate applies to. - `rate: str` Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%). - `as_of: Optional[datetime]` When the rate was requested from the locates venue. ### Example ```python from clearstreet import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.locates.get_locate_rate_by_id( "x", ) print(response) ``` #### 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 `v1.locates.get_locates(intaccount_id, LocateGetLocatesParams**kwargs) -> LocateGetLocatesResponse` **get** `/v1/accounts/{account_id}/locates` 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. ### Parameters - `account_id: int` - `effective_date: Optional[Union[null, null]]` Effective date to list; defaults to today's New York calendar date. Explicit dates are used unchanged, including weekends and holidays. - `instrument_ids: Optional[Sequence[InstrumentIDOrSymbol]]` Comma-separated instrument IDs (UUID) or symbols. - `status: Optional[List[Literal["REQUESTED", "ACCEPTED", "REJECTED", "EXPIRED"]]]` Comma-separated locate statuses to filter by - `"REQUESTED"` - `"ACCEPTED"` - `"REJECTED"` - `"EXPIRED"` ### Returns - `class LocateGetLocatesResponse: …` - `data: LocateList` - `account_id: int` Account the locate is booked to. - `client_request_id: str` Caller-assigned id of the locate request. - `effective_date: date` New York calendar date the locate is in force for. - `instrument_id: str` Instrument id. - `locate_request_id: str` Engine-assigned locate request id. - `requested_quantity: int` Number of shares requested. - `status: LocateStatus` Presented status of the locate. - `"REQUESTED"` - `"ACCEPTED"` - `"REJECTED"` - `"EXPIRED"` - `locate_id: Optional[str]` 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[int]` 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[str]` 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[int]` Number of granted shares reserved. When a null/undefined value is observed, it indicates it does not apply. - `used_quantity: Optional[int]` Number of granted shares already used. When a null/undefined value is observed, it indicates it does not apply. ### Example ```python from clearstreet import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.locates.get_locates( account_id=0, ) print(response) ``` #### 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 `v1.locates.get_locate_by_id(strid, LocateGetLocateByIDParams**kwargs) -> LocateGetLocateByIDResponse` **get** `/v1/accounts/{account_id}/locates/{id}` Fetch one locate by id, matched against the locate request id, locate id, and client request id, across all days in force. ### Parameters - `account_id: int` - `id: str` ### Returns - `class LocateGetLocateByIDResponse: …` - `data: Locate` A locate request joined with the locate granted for it, if any. - `account_id: int` Account the locate is booked to. - `client_request_id: str` Caller-assigned id of the locate request. - `effective_date: date` New York calendar date the locate is in force for. - `instrument_id: str` Instrument id. - `locate_request_id: str` Engine-assigned locate request id. - `requested_quantity: int` Number of shares requested. - `status: LocateStatus` Presented status of the locate. - `"REQUESTED"` - `"ACCEPTED"` - `"REJECTED"` - `"EXPIRED"` - `locate_id: Optional[str]` 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[int]` 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[str]` 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[int]` Number of granted shares reserved. When a null/undefined value is observed, it indicates it does not apply. - `used_quantity: Optional[int]` Number of granted shares already used. When a null/undefined value is observed, it indicates it does not apply. ### Example ```python from clearstreet import ClearStreet client = ClearStreet( api_key="My API Key", ) response = client.v1.locates.get_locate_by_id( id="id", account_id=0, ) print(response) ``` #### 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 - `class Locate: …` A locate request joined with the locate granted for it, if any. - `account_id: int` Account the locate is booked to. - `client_request_id: str` Caller-assigned id of the locate request. - `effective_date: date` New York calendar date the locate is in force for. - `instrument_id: str` Instrument id. - `locate_request_id: str` Engine-assigned locate request id. - `requested_quantity: int` Number of shares requested. - `status: LocateStatus` Presented status of the locate. - `"REQUESTED"` - `"ACCEPTED"` - `"REJECTED"` - `"EXPIRED"` - `locate_id: Optional[str]` 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[int]` 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[str]` 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[int]` Number of granted shares reserved. When a null/undefined value is observed, it indicates it does not apply. - `used_quantity: Optional[int]` Number of granted shares already used. When a null/undefined value is observed, it indicates it does not apply. ### Locate List - `List[Locate]` - `account_id: int` Account the locate is booked to. - `client_request_id: str` Caller-assigned id of the locate request. - `effective_date: date` New York calendar date the locate is in force for. - `instrument_id: str` Instrument id. - `locate_request_id: str` Engine-assigned locate request id. - `requested_quantity: int` Number of shares requested. - `status: LocateStatus` Presented status of the locate. - `"REQUESTED"` - `"ACCEPTED"` - `"REJECTED"` - `"EXPIRED"` - `locate_id: Optional[str]` 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[int]` 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[str]` 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[int]` Number of granted shares reserved. When a null/undefined value is observed, it indicates it does not apply. - `used_quantity: Optional[int]` Number of granted shares already used. When a null/undefined value is observed, it indicates it does not apply. ### Locate Rate - `class LocateRate: …` A locate borrow rate for an instrument. - `instrument_id: str` Instrument id the rate applies to. - `rate: str` Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%). - `as_of: Optional[datetime]` When the rate was requested from the locates venue. ### Locate Rate Result - `class LocateRateResult: …` 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: int` The error code is used to identify the nature of the error. It corresponds to an HTTP status code. - `message: str` A human-readable message providing more details about the error. - `details: Optional[List[Dict[str, object]]]` 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: str` Instrument id the rate applies to. - `rate: str` Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%). - `as_of: Optional[datetime]` When the rate was requested from the locates venue. ### Locate Rate Result List - `List[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: int` The error code is used to identify the nature of the error. It corresponds to an HTTP status code. - `message: str` A human-readable message providing more details about the error. - `details: Optional[List[Dict[str, object]]]` 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: str` Instrument id the rate applies to. - `rate: str` Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%). - `as_of: Optional[datetime]` When the rate was requested from the locates venue. ### Locate Status - `Literal["REQUESTED", "ACCEPTED", "REJECTED", "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 - `class LocateGetLocateRatesResponse: …` - `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: int` The error code is used to identify the nature of the error. It corresponds to an HTTP status code. - `message: str` A human-readable message providing more details about the error. - `details: Optional[List[Dict[str, object]]]` 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: str` Instrument id the rate applies to. - `rate: str` Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%). - `as_of: Optional[datetime]` When the rate was requested from the locates venue. ### Locate Get Locate Rate By ID Response - `class LocateGetLocateRateByIDResponse: …` - `data: LocateRate` A locate borrow rate for an instrument. - `instrument_id: str` Instrument id the rate applies to. - `rate: str` Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%). - `as_of: Optional[datetime]` When the rate was requested from the locates venue. ### Locate Get Locates Response - `class LocateGetLocatesResponse: …` - `data: LocateList` - `account_id: int` Account the locate is booked to. - `client_request_id: str` Caller-assigned id of the locate request. - `effective_date: date` New York calendar date the locate is in force for. - `instrument_id: str` Instrument id. - `locate_request_id: str` Engine-assigned locate request id. - `requested_quantity: int` Number of shares requested. - `status: LocateStatus` Presented status of the locate. - `"REQUESTED"` - `"ACCEPTED"` - `"REJECTED"` - `"EXPIRED"` - `locate_id: Optional[str]` 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[int]` 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[str]` 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[int]` Number of granted shares reserved. When a null/undefined value is observed, it indicates it does not apply. - `used_quantity: Optional[int]` 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 - `class LocateGetLocateByIDResponse: …` - `data: Locate` A locate request joined with the locate granted for it, if any. - `account_id: int` Account the locate is booked to. - `client_request_id: str` Caller-assigned id of the locate request. - `effective_date: date` New York calendar date the locate is in force for. - `instrument_id: str` Instrument id. - `locate_request_id: str` Engine-assigned locate request id. - `requested_quantity: int` Number of shares requested. - `status: LocateStatus` Presented status of the locate. - `"REQUESTED"` - `"ACCEPTED"` - `"REJECTED"` - `"EXPIRED"` - `locate_id: Optional[str]` 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[int]` 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[str]` 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[int]` Number of granted shares reserved. When a null/undefined value is observed, it indicates it does not apply. - `used_quantity: Optional[int]` Number of granted shares already used. When a null/undefined value is observed, it indicates it does not apply.