# Locates ## List Locate Rates `client.V1.Locates.GetLocateRates(ctx, query) (*V1LocateGetLocateRatesResponse, error)` **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 - `query V1LocateGetLocateRatesParams` - `InstrumentIDs param.Field[[]InstrumentIDOrSymbol]` Comma-separated instrument IDs (UUID) or symbols; at least one, at most 1,000. ### Returns - `type V1LocateGetLocateRatesResponse struct{…}` - `Data LocateRateResultList` - `Instrument InstrumentIDOrSymbol` The instrument id (UUID) or symbol, echoed exactly as requested, so each result maps back to its request. - `Error APIError` Why no rate is present — a `404` when the instrument is unknown or has no cached rate. Omitted when `rate` is present. - `Code int64` 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 []map[string, any]` Additional error details, if any. This can include structured information such as field violations or error metadata. - `Rate LocateRate` The cached borrow rate. Present when a rate was found; omitted when `error` is present. - `InstrumentID string` Instrument id the rate applies to. - `Rate string` Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%). - `AsOf Time` When the rate was requested from the locates venue. ### Example ```go package main import ( "context" "fmt" "github.com/clear-street/clear-street-go" "github.com/clear-street/clear-street-go/option" ) func main() { client := clearstreet.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.V1.Locates.GetLocateRates(context.TODO(), clearstreet.V1LocateGetLocateRatesParams{ InstrumentIDs: []clearstreet.InstrumentIDOrSymbol{"x"}, }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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 `client.V1.Locates.GetLocateRateByID(ctx, instrumentID) (*V1LocateGetLocateRateByIDResponse, error)` **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 - `InstrumentID InstrumentIDOrSymbol` Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side. ### Returns - `type V1LocateGetLocateRateByIDResponse struct{…}` - `Data LocateRate` A locate borrow rate for an instrument. - `InstrumentID string` Instrument id the rate applies to. - `Rate string` Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%). - `AsOf Time` When the rate was requested from the locates venue. ### Example ```go package main import ( "context" "fmt" "github.com/clear-street/clear-street-go" "github.com/clear-street/clear-street-go/option" ) func main() { client := clearstreet.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.V1.Locates.GetLocateRateByID(context.TODO(), "x") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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 `client.V1.Locates.GetLocates(ctx, accountID, query) (*V1LocateGetLocatesResponse, error)` **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 - `accountID int64` - `query V1LocateGetLocatesParams` - `EffectiveDate param.Field[Time]` Effective date to list; defaults to today's New York calendar date. Explicit dates are used unchanged, including weekends and holidays. - `InstrumentIDs param.Field[[]InstrumentIDOrSymbol]` Comma-separated instrument IDs (UUID) or symbols. - `Status param.Field[[]string]` Comma-separated locate statuses to filter by - `const V1LocateGetLocatesParamsStatusRequested V1LocateGetLocatesParamsStatus = "REQUESTED"` - `const V1LocateGetLocatesParamsStatusAccepted V1LocateGetLocatesParamsStatus = "ACCEPTED"` - `const V1LocateGetLocatesParamsStatusRejected V1LocateGetLocatesParamsStatus = "REJECTED"` - `const V1LocateGetLocatesParamsStatusExpired V1LocateGetLocatesParamsStatus = "EXPIRED"` ### Returns - `type V1LocateGetLocatesResponse struct{…}` - `Data LocateList` - `AccountID int64` Account the locate is booked to. - `ClientRequestID string` Caller-assigned id of the locate request. - `EffectiveDate Time` New York calendar date the locate is in force for. - `InstrumentID string` Instrument id. - `LocateRequestID string` Engine-assigned locate request id. - `RequestedQuantity int64` Number of shares requested. - `Status LocateStatus` Presented status of the locate. - `const LocateStatusRequested LocateStatus = "REQUESTED"` - `const LocateStatusAccepted LocateStatus = "ACCEPTED"` - `const LocateStatusRejected LocateStatus = "REJECTED"` - `const LocateStatusExpired LocateStatus = "EXPIRED"` - `LocateID 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 int64` Number of shares granted; set once the locate is granted. When a null/undefined value is observed, it indicates it does not apply. - `RelatedOrderID string` Client order id the request relates to, if any. When a null/undefined value is observed, it indicates it does not apply. - `ReservedQuantity int64` Number of granted shares reserved. When a null/undefined value is observed, it indicates it does not apply. - `UsedQuantity int64` Number of granted shares already used. When a null/undefined value is observed, it indicates it does not apply. ### Example ```go package main import ( "context" "fmt" "github.com/clear-street/clear-street-go" "github.com/clear-street/clear-street-go/option" ) func main() { client := clearstreet.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.V1.Locates.GetLocates( context.TODO(), 0, clearstreet.V1LocateGetLocatesParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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 `client.V1.Locates.GetLocateByID(ctx, id, query) (*V1LocateGetLocateByIDResponse, error)` **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 - `id string` - `query V1LocateGetLocateByIDParams` - `AccountID param.Field[int64]` Account identifier ### Returns - `type V1LocateGetLocateByIDResponse struct{…}` - `Data Locate` A locate request joined with the locate granted for it, if any. - `AccountID int64` Account the locate is booked to. - `ClientRequestID string` Caller-assigned id of the locate request. - `EffectiveDate Time` New York calendar date the locate is in force for. - `InstrumentID string` Instrument id. - `LocateRequestID string` Engine-assigned locate request id. - `RequestedQuantity int64` Number of shares requested. - `Status LocateStatus` Presented status of the locate. - `const LocateStatusRequested LocateStatus = "REQUESTED"` - `const LocateStatusAccepted LocateStatus = "ACCEPTED"` - `const LocateStatusRejected LocateStatus = "REJECTED"` - `const LocateStatusExpired LocateStatus = "EXPIRED"` - `LocateID 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 int64` Number of shares granted; set once the locate is granted. When a null/undefined value is observed, it indicates it does not apply. - `RelatedOrderID string` Client order id the request relates to, if any. When a null/undefined value is observed, it indicates it does not apply. - `ReservedQuantity int64` Number of granted shares reserved. When a null/undefined value is observed, it indicates it does not apply. - `UsedQuantity int64` Number of granted shares already used. When a null/undefined value is observed, it indicates it does not apply. ### Example ```go package main import ( "context" "fmt" "github.com/clear-street/clear-street-go" "github.com/clear-street/clear-street-go/option" ) func main() { client := clearstreet.NewClient( option.WithAPIKey("My API Key"), ) response, err := client.V1.Locates.GetLocateByID( context.TODO(), "id", clearstreet.V1LocateGetLocateByIDParams{ AccountID: 0, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", 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 - `type Locate struct{…}` A locate request joined with the locate granted for it, if any. - `AccountID int64` Account the locate is booked to. - `ClientRequestID string` Caller-assigned id of the locate request. - `EffectiveDate Time` New York calendar date the locate is in force for. - `InstrumentID string` Instrument id. - `LocateRequestID string` Engine-assigned locate request id. - `RequestedQuantity int64` Number of shares requested. - `Status LocateStatus` Presented status of the locate. - `const LocateStatusRequested LocateStatus = "REQUESTED"` - `const LocateStatusAccepted LocateStatus = "ACCEPTED"` - `const LocateStatusRejected LocateStatus = "REJECTED"` - `const LocateStatusExpired LocateStatus = "EXPIRED"` - `LocateID 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 int64` Number of shares granted; set once the locate is granted. When a null/undefined value is observed, it indicates it does not apply. - `RelatedOrderID string` Client order id the request relates to, if any. When a null/undefined value is observed, it indicates it does not apply. - `ReservedQuantity int64` Number of granted shares reserved. When a null/undefined value is observed, it indicates it does not apply. - `UsedQuantity int64` Number of granted shares already used. When a null/undefined value is observed, it indicates it does not apply. ### Locate List - `type LocateList []Locate` - `AccountID int64` Account the locate is booked to. - `ClientRequestID string` Caller-assigned id of the locate request. - `EffectiveDate Time` New York calendar date the locate is in force for. - `InstrumentID string` Instrument id. - `LocateRequestID string` Engine-assigned locate request id. - `RequestedQuantity int64` Number of shares requested. - `Status LocateStatus` Presented status of the locate. - `const LocateStatusRequested LocateStatus = "REQUESTED"` - `const LocateStatusAccepted LocateStatus = "ACCEPTED"` - `const LocateStatusRejected LocateStatus = "REJECTED"` - `const LocateStatusExpired LocateStatus = "EXPIRED"` - `LocateID 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 int64` Number of shares granted; set once the locate is granted. When a null/undefined value is observed, it indicates it does not apply. - `RelatedOrderID string` Client order id the request relates to, if any. When a null/undefined value is observed, it indicates it does not apply. - `ReservedQuantity int64` Number of granted shares reserved. When a null/undefined value is observed, it indicates it does not apply. - `UsedQuantity int64` Number of granted shares already used. When a null/undefined value is observed, it indicates it does not apply. ### Locate Rate - `type LocateRate struct{…}` A locate borrow rate for an instrument. - `InstrumentID string` Instrument id the rate applies to. - `Rate string` Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%). - `AsOf Time` When the rate was requested from the locates venue. ### Locate Rate Result - `type LocateRateResult struct{…}` 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 APIError` Why no rate is present — a `404` when the instrument is unknown or has no cached rate. Omitted when `rate` is present. - `Code int64` 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 []map[string, any]` Additional error details, if any. This can include structured information such as field violations or error metadata. - `Rate LocateRate` The cached borrow rate. Present when a rate was found; omitted when `error` is present. - `InstrumentID string` Instrument id the rate applies to. - `Rate string` Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%). - `AsOf Time` When the rate was requested from the locates venue. ### Locate Rate Result List - `type LocateRateResultList []LocateRateResult` - `Instrument InstrumentIDOrSymbol` The instrument id (UUID) or symbol, echoed exactly as requested, so each result maps back to its request. - `Error APIError` Why no rate is present — a `404` when the instrument is unknown or has no cached rate. Omitted when `rate` is present. - `Code int64` 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 []map[string, any]` Additional error details, if any. This can include structured information such as field violations or error metadata. - `Rate LocateRate` The cached borrow rate. Present when a rate was found; omitted when `error` is present. - `InstrumentID string` Instrument id the rate applies to. - `Rate string` Borrow rate, expressed as a decimal (e.g. 0.037012 for 3.7012%). - `AsOf Time` When the rate was requested from the locates venue. ### Locate Status - `type LocateStatus string` The presented status of a locate: the locate-request lifecycle plus `EXPIRED` for accepted locates whose effective date has passed. - `const LocateStatusRequested LocateStatus = "REQUESTED"` - `const LocateStatusAccepted LocateStatus = "ACCEPTED"` - `const LocateStatusRejected LocateStatus = "REJECTED"` - `const LocateStatusExpired LocateStatus = "EXPIRED"`