The Zendesk Search API
The Zendesk search API is the endpoint people reach for first and regret third. Excellent for finding a handful of records, quietly wrong for pulling data at scale.
The shape of a Zendesk search API query
One endpoint, GET /api/v2/search.json?query=..., with the query string URL-encoded. The syntax is the same one your agents type into the search box, which is genuinely useful: you can prototype a query in the interface and then paste it into code.
The building blocks are simple.
type:ticket, type:user, type:organization, type:group. Always set it. Without it you get a mixed bag of record types and pay for results you'll throw away.keyword:value, such as status:open, tags:refund, group:billing, assignee:none, requester:someone@example.com.created>2026-01-01, status<solved, updated>24hours. The status<solved form is the workhorse for "everything still live".- to exclude, as in -tags:spam.Terms combine with an implicit AND. Sorting works through sort_by and sort_order on a small set of fields such as created and updated dates, so don't plan a UI around sorting by anything clever.
What search won't do
The gaps matter more than the syntax, because each one has produced somebody a broken integration.
Results are capped. A single query returns a bounded number of results, in the low thousands, and paging further simply stops. If your query could match more than that, search is the wrong tool and no amount of paging will fix it.
The index lags. Search runs against an index, not against the live database. A ticket created a moment ago may not be findable for several seconds, occasionally longer. Any workflow shaped like "create it, then search for it to confirm" is a race you will lose intermittently, which is the worst kind of bug to diagnose.
Wildcards are limited. Trailing wildcards work in places. Leading wildcards do not, so you cannot search for a fragment in the middle of an order number and expect a match.
Archived tickets are inconsistent. Tickets that have been closed long enough to be archived do not behave like live ones in search results. If your report is missing everything older than a few months, that is why.
Rate limits are tighter here. Search has its own, lower, per-minute allowance separate from the general API limit. It's easy to be well within your account limit and still get 429s from search alone. There is a separate export flavour of the endpoint that trades a stricter result shape for cursor pagination over larger sets, and it's worth knowing about, but it is limited too.
Use incremental exports for bulk
If what you want is "everything that changed since I last looked", search isn't the answer. Incremental exports are.
The incremental endpoints take a start time and return records changed since then, a thousand at a time, with a cursor to continue. They read from the database rather than the search index, so there is no lag and no result ceiling. They also include archived tickets and, importantly, tell you about deletions, which search can't do at all.
The catch is that they are rate limited to a small number of requests per minute, deliberately, because each one is expensive. Fine for a sync job, useless for anything interactive. That is the split to design around: incremental exports for the nightly job that keeps your warehouse honest, search for the agent-facing lookup that needs an answer in half a second.
One detail people get wrong: incremental results are inclusive of the start time, so the last record of one run reappears at the start of the next. Deduplicate on ID.
Making search fast enough to use
Narrow before you sort. type:ticket status<solved group:billing created>30days returns a small set quickly. The same query without the type or the date range asks Zendesk to consider your entire history and then hand you the first page of it.
Cache aggressively. If a sidebar app searches for a customer other tickets every time an agent opens one, you're spending your tightest rate limit on a question whose answer barely changes. Even a sixty second cache removes most of that traffic. Use the count endpoint when you only need a number, too, since asking how many open tickets an organisation has doesn't require fetching them.
And handle 429 properly. Read Retry-After, wait, retry with jitter. A tight retry loop against a rate-limited endpoint is how one badly behaved script degrades search for every agent on the account.
The duplicate-finding use case
The most common reason people write a search integration is checking whether a ticket already exists before creating another one. It's a good instinct, and search is a poor tool for it.
Three reasons. The index lag means the ticket you are checking for may have been created two seconds ago and be invisible. Text similarity is not something the query syntax can express, so you can match on requester and recency but not on "these two describe the same problem". And the result cap makes any broad query unreliable.
You can get partway there: search by requester: plus created>1hour plus status<solved catches the obvious case of somebody writing in twice. Just do not expect it to catch the same person emailing from a work address on Monday and a personal one on Tuesday.
Frequently asked questions
What is the Zendesk search syntax for tickets?
Field-colon-value pairs, like type:ticket status:open. The Zendesk search tickets API takes the same query string as the agent interface, and for anything large the Zendesk export search API is the endpoint that paginates properly.
How many results can the Zendesk search API return?
A single query is capped in the low thousands and paging stops there. For anything larger, use the incremental export endpoints instead.
Why does a ticket I just created not appear in search?
Search runs against an index that lags the database by seconds. Never build a create-then-search confirmation step around it.
Does search include closed and archived tickets?
Closed tickets are searchable, but archived ones behave inconsistently in results. Incremental exports are the reliable way to see everything.
What is the search rate limit?
Search has its own per-minute allowance, separate from and lower than the general API limit. You can be inside your account limit and still be throttled on search.
Can I search inside ticket comments?
Free-text terms match comment content, but the matching is keyword-based, not semantic. Two tickets describing the same problem in different words will not match each other.
Similar isn't the same as matching keywords
Ticket Merger scores tickets on wording, requester and timing together, which is the comparison a search query cannot express.
Start free trial14-day free trial. No credit card required.