Speed has set a standardization for SQL so you can make a query and get faster results. If you do not want to paginate through all the objects of a particular resource to find your match, Search APIs are the best way to go.

Right now, Search API is available for below mentioned resources:

For you to use search via APIs on these mentioned resources, you need to understand how to make a query clause that will fetch you a result. This query is a clause made up of fields, values, and an operator between them.

Additionally, a query can have multiple clauses in it. See more about this here.

Let’s see the structure and syntax to formulate a proper query.

Query structure

A query clause consists of a field followed by an operator followed by a value.

fieldemailFields are what content you are searching for from the object, like email, date, etc.
operator:Operators are used for searching the matching value of an object. Operators are greater than (>), less than (<), equals to (=), and many others.
value[email protected]It is the value of the field for which you want the match. Like [email protected], 12/09/2022, etc.

All of this formulates a query clause. Example: email:"[email protected]".You must use quotation marks around string values. Quotation marks are optional for numeric values.

Concatenating multiple clauses

You can combine multiple clauses in a search query by either separating them with a space or using the AND. By default, the API combines clauses with AND logic.

Example: "amount>120 status:paid”

Field types

Each field has a type that defines the operators you can use with it. Below is the full list of supported query fields and their types for each resource.

Payment fields
Field Name UsageType
Target Amounttarget_amount>1000Numeric
Descriptiondescription:”order id:23”String
Target Currencytarget_currency:”sats”Token
Target Amount Paidtarget_amount_paid>1000Numeric
Statement Descriptorstatement_descriptor:”payment”String
Checkout link fields
Field NameUsageType
Target Currencytarget_currency:”SATS”Token
Statement Descriptorstatement_descriptor:”payment”String
Payment IDpayment_id:”pi_l7ee7apsiLQ9pkOB”Token
Payment link fields
Field NameUsageType
Target Currencytarget_currency:”btc”Token
Statement Descriptorstatement_descriptor:”payment”String
Payment IDpayment_id:”pi_l7ee7apsiLQ9pkOB”Token


Every search field supports exact matching using the : operator. Fields such as amount support numeric operators like > and <. Using an unsupported operator, such as specifying greater than (>) on a string, returns an error. Substring matching is also supported in some fields, including email and name.

Let us see the operators available based on the field type.

tokenexact match (case insensitive)
stringexact match (:), substring (~)   (case insensitive)
numeric>(greater than)
<(less than)
<=(less than or equal)
>=(greater than or equal)
..(is between)


The following table lists the syntax that you can use to construct a query.

:field:valueExact match operator (case insensitive)currency:"eur" returns records where the currency is exactly “EUR” in a case-insensitive comparison
AND, andfield:value1 AND field:value2The query returns only records that match both clauses (case insensitive)status:"active" AND amount:500
--field:valueYou can negate query clauses using a - character.Returns records that don’t match the clause-currency:"jpy" returns records that aren’t in JPY.
\ " """Escape quotes within quotesdescription:"the story called "The Sky and the Sea.""
~field~valueSubstring match operatoremail~"amy" returns matches for [email protected] and xamy
>, <, =field<value
Greater than/less than operatorsamount>="10" brings up objects where the amount is 10 or greater
..field:value1..value2Returns field having value in between value 1 and value2amount:1..100 brings up objects where the amount is between 1 and 100

Cursor-based pagination is possible in Search APIs via the page request parameter and next_page response parameter.

Data freshness

When a resource is created, avoid using search right away because the data won't be immediately accessible. Under normal operating conditions, data is searchable in under 1 minute. Propagation of new or updated data could be more delayed during an outage.

Rate limits

We apply a rate limit of up to 50 requests per second (test mode) and 200 requests per second (live mode) to all search endpoints.

💡 Using the web search available on the Speed web application you can easily find your data in a similar manner. Learn more about this here.