Search

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.


field	email	Fields 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	Usage	Type
ID	id:”pi_l3v6fgis9h9YcDIV”	Token
Amount	amount>1000	Numeric
Target Amount	target_amount>1000	Numeric
Description	description:”order id:23”	String
Status	status:”paid”	Token
Created	created>1620310503	Numeric
Target Currency	target_currency:”sats”	Token
Currency	currency:”usd”	Token
Target Amount Paid	target_amount_paid>1000	Numeric
Statement Descriptor	statement_descriptor:”payment”	String
Metadata	metadata[‘key_1’]:value_1	Token

Checkout link fields

Field Name	Usage	Type
Created	created>1659356955920	Numeric
Currency	currency:”usd”	Token
Amount	amount>500	Numeric
Target Currency	target_currency:”SATS”	Token
Status	status:”active”	Token
URL	url:”cs_test_l3mvy93hxOTgrJAV”	String
Statement Descriptor	statement_descriptor:”payment”	String
ID	id:”clink_test_123456789”	Token
Payment ID	payment_id:”pi_l7ee7apsiLQ9pkOB”	Token
Metadata	metadata[‘key_1’]:value_1	Token

Payment link fields

Field Name	Usage	Type
Created	created>1662693406398	Numeric
Amount	amount>=500	Numeric
Currency	currency:”usd”	Token
Target Currency	target_currency:”sats”	Token
Status	status:”deactivated”	Token
URL	url:”plink_test_l8claw5l5AOR6Bon”	String
Statement Descriptor	statement_descriptor:”payment”	String
ID	id:”plink_21312”	Token
Payment ID	payment_id:”pi_l7ee7apsiLQ9pkOB”	Token
Metadata	metadata[‘key_1’]:value_1	Token

Customers fields

Field Name	Usage	Type
ID	id:”cus_lkw4k0n4yAI6yLsq”	String
Name	name: "John”	String
Email	email: "john”	String
Active	active:true or false	Token
billing_phone	billing_phone: "7506119541”	String
metadata	metadata["key"]:"value”	String
created	created>1650907271771	Numeric

Products fields

Field Name	Usage	Type
ID	id:”prod_8521HGkjl04”	String
Name	name:”product”	String
Active	active:true or false	Token
metadata	metadata["key"]:"value”	String
created	created>1650907271771	Numeric
description	description:”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.

TYPE	OPERATORS
token	exact match (case insensitive)
string	exact 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.

SYNTAX	USAGE	DESCRIPTION	EXAMPLES
:	field:value	Exact match operator (case insensitive)	currency:"eur" returns records where the currency is exactly “EUR” in a case-insensitive comparison
AND, and	field:value1 AND field:value2	The query returns only records that match both clauses (case insensitive)	status:"active" AND amount:500
-	-field:value	You 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 quotes	description:"the story called "The Sky and the Sea.""
~	field~value	Substring match operator	email~"amy" returns matches for [email protected] and xamy
>, <, =	field<value field>value field>=value field<=value	Greater than/less than operators	amount>="10" brings up objects where the amount is 10 or greater
..	field:value1..value2	Returns field having value in between value 1 and value2	amount: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.