Filtering & Query Operators

The search query parameter lets you filter rows server-side before they reach your application. It accepts a field:value expression that supports a range of operators for exact matching, substring matching, numeric comparisons, negation, and OR logic.

GET https://api.gkit.io/api/spreadsheets/{userKey}/{sheetName}?search=field:value
Authorization: Bearer sk_...

Response shape:

{
  "data": [...],
  "meta": { "total": 42, "limit": 20, "offset": 0 }
}

meta.total reflects the filtered row count, not the full sheet size.

Operators

Field names are case-sensitive and must match the header row of your sheet exactly. Values are case-insensitive for string fields.

Code examples

Exact match

Return only rows where status is exactly active:

curl "https://api.gkit.io/api/spreadsheets/uk_abc123/Orders?search=status%3Aactive" \
  -H "Authorization: Bearer sk_..."

Contains substring

Find rows where the name column contains john anywhere in the value:

curl "https://api.gkit.io/api/spreadsheets/uk_abc123/Contacts?search=name%3A*john*" \
  -H "Authorization: Bearer sk_..."

Numeric range

Return products priced above 100 and at most 500:

curl "https://api.gkit.io/api/spreadsheets/uk_abc123/Products?search=price%3A%3E100&search=price%3A%3C%3D500" \
  -H "Authorization: Bearer sk_..."

Multiple search parameters are combined with AND logic, so both conditions must hold.

OR logic

Match rows where status is either active or pending:

curl "https://api.gkit.io/api/spreadsheets/uk_abc123/Orders?search=status%3Aactive%7Cpending" \
  -H "Authorization: Bearer sk_..."

Negation

Exclude rows where tier is free:

curl "https://api.gkit.io/api/spreadsheets/uk_abc123/Users?search=tier%3A%21free" \
  -H "Authorization: Bearer sk_..."

Combining with sort, limit, and offset

All query parameters compose freely. The filter is applied first, then sorting, then pagination - so meta.total always reflects filtered results and page offsets are stable.

# Active orders sorted newest-first, page 2 (25 per page)
curl "https://api.gkit.io/api/spreadsheets/uk_abc123/Orders\
?search=status%3Aactive\
&sort=-created_at\
&limit=25\
&offset=25" \
  -H "Authorization: Bearer sk_..."

In JavaScript, use URLSearchParams to handle encoding automatically:

const params = new URLSearchParams({
  sort: "-created_at",
  limit: "25",
  offset: "25",
});
// Append multiple search conditions
params.append("search", "status:active");
params.append("search", "tier:pro|enterprise");
 
const res = await fetch(`https://api.gkit.io/api/spreadsheets/${userKey}/Orders?${params}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const { data, meta } = await res.json();

Notes

• URL encoding is required. Operator characters must be percent-encoded in raw URLs: : → %3A, * → %2A, > → %3E, < → %3C, ! → %21, | → %7C. HTTP client libraries (fetch, axios, httpx, curl with --data-urlencode) encode values automatically when you build the URL through their parameter API.
• Rows with a missing or blank field are excluded when a search filter targets that field. If a row has no value in the tier column, search=tier:!free will not include it.
• Numeric operators (>, <, >=, <=) cast the column value to a number before comparing. Cells that cannot be parsed as a number are treated as non-matching and excluded from results.
• OR logic is per-field only. The pipe syntax (val1|val2) applies within a single field:value expression. Cross-field OR is not supported - use separate requests and merge client-side if needed.

See Query Parameters for the full list of supported parameters, and Advanced Filtering for patterns that combine filtering with field projection and pagination.