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, metadata, 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 metadata[‘key_1’]:value_1"

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
IDid:”pi_l3v6fgis9h9YcDIV”Token
Amountamount>1000Numeric
Target Amounttarget_amount>1000Numeric
Descriptiondescription:”order id:23”String
Statusstatus:”paid”Token
Createdcreated>1620310503Numeric
Target Currencytarget_currency:”sats”Token
Currencycurrency:”usd”Token
Target Amount Paidtarget_amount_paid>1000Numeric
Statement Descriptorstatement_descriptor:”payment”String
Metadatametadata[‘key_1’]:value_1Token
Checkout link fields
Field NameUsageType
Createdcreated>1659356955920Numeric
Currencycurrency:”usd”Token
Amountamount>500Numeric
Target Currencytarget_currency:”SATS”Token
Statusstatus:”active”Token
URLurl:”cs_test_l3mvy93hxOTgrJAV”String
Statement Descriptorstatement_descriptor:”payment”String
IDid:”clink_test_123456789”Token
Payment IDpayment_id:”pi_l7ee7apsiLQ9pkOB”Token
Metadatametadata[‘key_1’]:value_1Token
Payment link fields
Field NameUsageType
Createdcreated>1662693406398Numeric
Amountamount>=500Numeric
Currencycurrency:”usd”Token
Target Currencytarget_currency:”sats”Token
Statusstatus:”deactivated”Token
URLurl:”plink_test_l8claw5l5AOR6Bon”String
Statement Descriptorstatement_descriptor:”payment”String
IDid:”plink_21312”Token
Payment IDpayment_id:”pi_l7ee7apsiLQ9pkOB”Token
Metadatametadata[‘key_1’]:value_1Token
Customers fields
Field NameUsageType
IDid:”cus_lkw4k0n4yAI6yLsq”String
Namename: "John”String
Emailemail: "john”String
Activeactive:true or falseToken
billing_phonebilling_phone: "7506119541”String
metadatametadata["key"]:"value”String
createdcreated>1650907271771Numeric
Products fields
Field NameUsageType
IDid:”prod_8521HGkjl04”String
Namename:”product”String
Activeactive:true or falseToken
metadatametadata["key"]:"value”String
createdcreated>1650907271771Numeric
descriptiondescription:”test product”String

Operators

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.

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

Syntax

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

SYNTAXUSAGEDESCRIPTIONEXAMPLES
: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
field>value
field>=value
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
Pagination

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.