# Locates ## List Locate Rates `$ clst v1:locates get-locate-rates` **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-id: array of InstrumentIDOrSymbol` Comma-separated instrument IDs (UUID) or symbols; at least one, at most 1,000. ### Returns - `V1LocateGetLocateRatesResponse: BaseResponse` - `data: array of LocateRateResult` - `instrument: string` The instrument id (UUID) or symbol, echoed exactly as requested, so each result maps back to its request. - `error: optional object { code, message, details }` 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 object { instrument_id, rate, as_of }` 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 ```cli clst v1:locates get-locate-rates \ --api-key 'My API Key' \ --instrument-id x ``` #### 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 `$ clst v1:locates get-locate-rate-by-id` **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: string` Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side. ### Returns - `V1LocateGetLocateRateByIDResponse: BaseResponse` - `data: 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. ### Example ```cli clst v1:locates get-locate-rate-by-id \ --api-key 'My API Key' \ --instrument-id x ``` #### 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 `$ clst v1:locates get-locates` **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: number` Account identifier - `--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-id: 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 ### Returns - `V1LocateGetLocatesResponse: BaseResponse` - `data: 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: "REQUESTED" or "ACCEPTED" or "REJECTED" or "EXPIRED"` 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 ```cli clst v1:locates get-locates \ --api-key 'My API Key' \ --account-id 0 ``` #### 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 `$ clst v1:locates get-locate-by-id` **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: number` Account identifier - `--id: string` Locate request id, locate id, or client request id ### Returns - `V1LocateGetLocateByIDResponse: BaseResponse` - `data: 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: "REQUESTED" or "ACCEPTED" or "REJECTED" or "EXPIRED"` 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 ```cli clst v1:locates get-locate-by-id \ --api-key 'My API Key' \ --account-id 0 \ --id id ``` #### 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: "REQUESTED" or "ACCEPTED" or "REJECTED" or "EXPIRED"` 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 - `locate_list: 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: "REQUESTED" or "ACCEPTED" or "REJECTED" or "EXPIRED"` 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 - `locate_rate: 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 - `locate_rate_result: object { instrument, error, rate }` A requested instrument with either its cached borrow rate or an error. - `instrument: string` The instrument id (UUID) or symbol, echoed exactly as requested, so each result maps back to its request. - `error: optional object { code, message, details }` 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 object { instrument_id, rate, as_of }` 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 - `locate_rate_result_list: array of LocateRateResult` - `instrument: string` The instrument id (UUID) or symbol, echoed exactly as requested, so each result maps back to its request. - `error: optional object { code, message, details }` 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 object { instrument_id, rate, as_of }` 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 - `locate_status: "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"`