Search and filter requests

Every request ApiTraffic captures can be found with a short query such as status_code >= 500 AND url_path like "/v1/payments/*". The same language (the criteria language) is used everywhere you pick out requests: the request log, stream views, workflows, exclusions, embeds, the REST API and the MCP server. Learn it once and use it in all of them.

Build a filter in the request log #

Open any request log view (All Traffic, Inbound Traffic, Outbound Traffic, Errors or Captures). The filter bar sits above the status code chart.

Start a filter

Select Click to add filter…. A Field menu opens, grouped into Request, Response, Performance, Firewall and Metadata. Type in Search fields to narrow it.

Pick the field and, for keyed fields, the key

For Request Header, Response Header, Query Param and Tag, a Context menu follows with the keys seen in the current results. Choose Other to type a key that isn’t listed.

Pick an operator and enter a value

Choose an Operator, then type a Value. Fields with known values, such as Method or Status Code, also offer Suggestions; you can still type anything. For like, the placeholder reminds you that * matches anything.

Add it

Select Add or press Enter. The condition becomes a chip and the log reloads. Add more filters with the + after the last chip; every chip is joined with AND.

Building a second filter with the filter builder.

Select a chip to edit it (Update saves the change), or the × on a chip to remove it. Removing the last chip shows the view’s full log again.

Type a query in Advanced mode #

Select Advanced above the filter bar to edit the query as text. Press Enter (or move focus out of the box) to run it; Shift+Enter adds a line break. Select Filter builder to go back to chips.

The same kind of filter typed in Advanced mode.

Advanced mode accepts every field in this page, including the ones the builder doesn’t list (received, capture, sid, context_sid, body search and the AI traffic fields).

Link to a filtered log #

The request log reads a criteria query parameter, so you can bookmark or send a pre-filtered view. URL-encode the query:

https://app.apitraffic.io/buckets/<bucketSid>/errors?criteria=url_path%20like%20%22%2Fv1%2Fpayments%2F*%22

To keep a filter for the whole team, save it as a stream view instead.

Query syntax #

A query is one or more conditions joined with AND:

field operator value
field:key operator value
field operator value AND field operator value

• Join with uppercase AND, with a space on each side. Lowercase and is not a separator, and neither is AND inside a word: tag:db == ORACLE and tag:os == ANDROID are one condition each. To match the word AND or OR on its own, quote it (tag:op == "OR").
• Put string values in double quotes: method == "POST". A quoted value can contain spaces and operators. Inside quotes, write \" for a literal double quote and \\ for a backslash.
• Write numbers without quotes: status_code >= 500, duration > 1000.
• Keyed fields name the key after a colon: request_header:content-type == "application/json", tag:tenant == "acme".
• Field names are checked. An unknown field is rejected with Invalid Condition: The keyword ... is not valid., so a typo shows an error instead of quietly returning the wrong requests.
• A query can have at most 50 conditions when it is saved (stream views, workflows), and each value at most 1,024 characters.

Warning: Conditions can only be combined with AND, and parentheses aren’t supported. A query with OR between conditions is refused with Invalid Syntax: OR is not supported. To see two alternatives, run two searches, or use like with a wildcard where the values share a pattern (url_path like "/v1/cart/*").

OR used to be accepted and silently treated like AND. Stream views, workflows, exclusion rules and firewall criteria rules saved that way keep running as they always have, as AND (every condition must match), but can’t be saved again until OR is replaced: write AND to keep what they do, or make one per alternative. A saved view with OR shows the error when you open it.

Operators #

How like works. The pattern must match the whole value. * matches any run of characters (including none) and is the only wildcard; every other character, including %, _, ? and ., is literal. Matching is case-sensitive.

Note: Exclusion rules and firewall criteria rules run inside your SDK, where a like value is a regular expression rather than a wildcard pattern. Everywhere else (search, stream views, workflows), like is the wildcard match above.

A firewall criteria rule decides before your API responds, so it can only use request fields: method, url, url_path, host, request_header, query_param, request_size (the Content-Length header) and direction. Your SDK also reads a firewall criteria rule more simply than search does: a leading - or ! is ignored by SDK releases before the current one, header names must be lower case, escapes, quotes or operators inside a value aren’t read the same way, and >, >=, < and <= compare request_size as text, and headers and query parameters as text in SDK releases before the current one ("999" is greater than "1000"), so only == and != work on them. From the current release on, a firewall criteria rule on query_param: also sees the bracketed forms of the parameter: ?debug[]=1, ?debug[0]=1, ?debug[a]=1 and ?[debug]=1 count as values of debug, as Express 4 (the qs query parser) hands them to your app. With a parser that keeps debug[] as its own key (Express 5’s default, Fastify), the rule can match requests your app does not read as debug. Saving a policy whose criteria rule uses another field, an unknown field, any of those, or criteria that can’t be parsed is refused. To match the opposite, use != or set the rule’s negate field.

Exclusion rules are read the same way, so an exclusion with a leading - or !, with >, >=, < or <= on a header, query parameter, tag, request_size, response_size, waf_score or a text field, or with a condition on received (SDK releases before the current one never read it), is refused too, and one saved before is sent to your servers turned off. See Exclusions.

Exclude matching requests #

Put - (or !) in front of a field to keep only the requests a condition does not match (not in exclusion or firewall criteria rules; use != there):

-url_path like "/v1/products*"
status_code >= 400 AND -status_code == 404

Missing values #

A condition on a value a request doesn’t carry, such as a tag or header it doesn’t have, never matches. That includes !=: tag:tenant != "acme" matches requests that have a tenant tag with another value, not requests without the tag. An exclusion is the opposite, so -tag:tenant == "acme" keeps requests without the tag too.

When a tag or header repeats, the condition matches if any of its values does (for !=, if none equals).

Fields #

Request fields #

Warning: query_param is evaluated by stream view workflows and by exclusion rules, but the request log can’t search on it yet. To find a query parameter in the log, match the full URL instead: url like "*page=7*".

Response fields #

Metadata fields #

Performance fields #

Performance fields come from APM. They are filled in only for traffic from SDKs with APM enabled; elsewhere they read as 0.

All performance fields are numbers and take every numeric operator.

Firewall fields #

The web application firewall records its decision on each inbound request it matches. These fields read that decision. They are shorthand for the waf.* tags, so waf_action == "block" and tag:waf.action == "block" are the same query.

AI traffic fields #

For MCP, JSON-RPC and LLM API calls, ApiTraffic records a short summary you can search in Advanced mode:

These fields are not available in exclusions or firewall criteria rules. Both run in your SDK, and ApiTraffic works out the summary only after the SDK has sent the request, so saving an exclusion or a policy that uses one of these fields is refused.

Search request and response bodies #

Two more fields search the bodies themselves, in Advanced mode:

Body fields search what ApiTraffic stored, so they are not available in exclusions or firewall criteria rules. like matches the whole body, so wrap the text you are looking for in *:

response_body like "*out_of_stock*"
method == "POST" AND request_body like "*shippingAddress*"

Body search needs all of the following:

• A plan that includes Body search. Without it, a body condition is refused with Body search criteria requires body-search entitlement.
• Body logging turned on for the bucket. Bodies are indexed for search only when the bucket’s searchBodyLogging setting is request, response or both. It is none by default and is set through the buckets API. Changing it affects newly captured traffic only.
• Bodies within your plan’s body retention. Older bodies are no longer stored and can’t match.

Bodies are indexed after redaction, so redacted values can’t be found by searching for them.

Warning: A body search finds at most the 2,000 newest matching requests per lookup. The request log keeps paging back through older matches as you scroll, but the status code chart and other counts can’t, and fail with the body condition matches more than 2000 requests in this window; narrow the time range or add filters. Add other conditions (an endpoint, a status code) and a shorter time range to keep body searches fast.

Cookbook #

Ready-made queries, using the endpoints and providers in the sample bucket. Paste any of them into Advanced mode.

Errors #

Latency #

Outbound calls #

Firewall #

Time windows, headers and bodies #

The sample bucket doesn’t attach custom tags, so the last query returns nothing there. In your own app, add tags with the SDK’s tag() function; see Tags.

Search from the API and MCP #

The same queries work outside the app:

• REST API. GET /v1/accounts/{accountSid}/buckets/{bucketSid}/requests takes the query in the criteria parameter (URL-encoded), along with startTime, endTime, environmentSid and limit (default 25, at most 100). Results page with the opaque from token. See Requests API.
• MCP. The search_requests tool takes the query as query. Prefer its dedicated arguments where they fit (window, method, statusCode, statusMin, statusMax, pathLike, minDurationMs, direction); they are combined with query using AND. The current grammar, generated from the query engine itself, is the MCP resource apitraffic://criteria-dsl.
• Saved views. An MCP client can list the team’s stream views with list_saved_views and pass a view’s criteria to search_requests.

Troubleshooting #

That search could not be run

The message under the filter bar names the problem. Common causes: an unknown field (Invalid Condition: The keyword ... is not valid.), a condition with no operator or two operators (Invalid Syntax: ... is not allowed.), or a value with an unescaped double quote. Quote values that contain spaces or operators, and escape a literal quote as \".

My like pattern finds nothing

like must match the whole value and is case-sensitive. Add * at the start or end (url_path like "*/capture"), and check the case. % and _ are not wildcards.

A != or numeric condition skips some requests

Requests that don’t carry the value at all never match a condition on it, including !=. Use an exclusion (-tag:tenant == "acme") to keep requests without the tag. A header or tag compared with > or < only matches when its value is a number.

An endpoint filter returns nothing

endpoint holds the template without the method, for example /v1/orders/{order_id}, not GET /v1/orders/{order_id}. Copy the exact name from the Endpoints page, or use Find Similar on a request and pick Endpoint.

Body search is refused or finds nothing

Check that your plan includes Body search, that body logging is on for the bucket, and that the bodies are within your plan’s body retention. Only traffic captured after body logging was turned on can match.

Related #

• Stream views: Save a query and share it with your team.

• Request details: Use Find Similar to turn a request into a query.

• MCP tools: Search requests from your AI coding agent.

• Workflows: Act on every new request that matches a query.