Ghost Query Language (GQL)

When you have hundreds or thousands of captured flows, you need a fast way to find the ones you care about. Ghost Query Language (GQL) is a simple search syntax you type into the search bar to filter traffic. Instead of clicking through menus, you type queries like method:POST status:>399 host:api.example.com and instantly see only the matching flows.

You don’t need to memorize this syntax — Ghost shows autocomplete hints as you type, and there are quick filter buttons for common queries. But learning GQL lets you build precise filters faster than any click-based interface.

GQL is used in three places:

1. The search bar at the top of the traffic view
2. Filter presets (quick buttons below the search bar)
3. The AI agent’s search_traffic tool — the agent uses GQL internally when you ask it to find specific traffic

Syntax

GQL queries use field:value pairs. You can combine multiple pairs — they’re AND-combined, meaning all conditions must match for a flow to appear in the results.

method:POST status:>399 host:api.example.com

This query means: “show me all flows where the method is POST AND the status code is greater than 399 (meaning 4xx or 5xx errors) AND the hostname is api.example.com.”

Negation: Prefix any field with - to exclude matches. For example, -host:fonts.gstatic.com hides all traffic to Google Fonts. -method:OPTIONS hides CORS preflight requests.

Multiple values (OR): Repeating the same field OR’s the values together. For example, method:GET method:POST shows flows that are either GET or POST. status:2xx status:4xx shows both successes and client errors.

Free text search: If you type text without a field: prefix, Ghost performs a full-text search across URLs, headers, and bodies using the body: field internally. For example, typing login password searches for flows that contain both “login” and “password” anywhere in their request or response data.

Supported Fields

Field	Operators	Example	What It Filters
method	: (exact match)	method:POST	The HTTP method. Case-insensitive (auto-uppercased). Common values: GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD. Multiple values are OR’d: method:GET method:POST shows both.
status	: (exact), >, <, >=, <=, range shorthand	status:200, status:>399, status:<300, status:2xx, status:4xx	The HTTP response status code. Supports range shorthand: status:2xx matches 200-299, status:4xx matches 400-499. Multiple values/ranges are OR’d: status:2xx status:4xx shows successes and client errors.
host	: (smart match)	host:api.example.com, host:api	The hostname. Smart matching: dotted values like host:hepsiburada.com use suffix match (also matches www.hepsiburada.com, api.hepsiburada.com). Non-dotted values like host:api use substring match (matches any host containing “api”).
path	: (substring match)	path:/api/users	The URL path (everything after the hostname). Substring match: path:/checkout finds all requests to paths containing “/checkout”.
content_type	: (substring match)	content_type:json	The response content type. content_type:json finds JSON responses (application/json). content_type:html finds HTML pages. Multiple values are OR’d.
tag	: (substring match)	tag:error	Flow tags — both user-added tags and system tags. tag:__bookmarked finds starred flows. tag:security:header-missing finds flows flagged by the security interceptor.
has	: (property check)	has:interaction	Checks whether a flow has a specific property. Three values supported: has:interaction = has correlated browser interactions, has:error = the request failed, has:response = the server responded.
duration	>, <, >=, <=	duration:>1000	Request-response duration in milliseconds. duration:>1000 finds requests that took more than 1 second. Stored internally as nanoseconds (the ms value you provide is converted automatically).
size	>, <, >=, <=	size:>10000	Response body size in bytes. size:>10000 finds responses larger than ~10KB. Uses COALESCE(LENGTH(resp_body), 0) so flows without a response body count as 0.
source	: (exact match)	source:replay	Where the flow came from. Values: proxy (normal traffic), replay (replayed request), script (generated by security tools or injected scripts), import (imported from HAR or other source).
body	: (FTS match)	body:"search term"	Full-text search on request and response bodies. Wrap multi-word terms in quotes. Uses the FTS5 index with porter stemming.
(free text)	(full-text search)	login password	Searches across request URLs, host, path, headers, bodies, notes, and tags. Finds any flow containing the search terms in any indexed field.

Examples

Here are practical search queries for common QA and security testing scenarios:

Find all API errors

method:POST status:>399 content_type:json

Shows POST requests to JSON APIs that returned error status codes (400+). This is often the first thing you check after running through a test flow — “did any API calls fail?”

Find slow requests

duration:>1000 host:api.example.com

Shows requests to api.example.com that took more than 1 second. Performance issues in specific API endpoints often surface here.

Find login-related traffic

login auth token

Full-text search across all flow data for the words “login,” “auth,” and “token.” This catches login endpoints, authentication headers, token exchanges, and related traffic regardless of the specific URL structure.

Find bookmarked flows

tag:__bookmarked

Shows only flows you’ve starred/bookmarked. Useful when you’ve marked important flows during a testing session and want to come back to them.

Find flows with browser interactions

has:interaction

Shows flows that have correlated browser interactions — meaning the Ghost extension recorded a user action (click, form input, navigation) that happened around the same time as this network request. This helps answer “what did the user do that triggered this API call?”

Find security test traffic

source:script

Shows flows generated by Ghost’s scripting and security testing tools (Request Attacker, AI agent security probes, injected scripts). In Security mode, these are visible by default. In QA mode, they’re hidden.

Exclude noisy domains

-host:fonts.googleapis.com -host:cdn.example.com

Hides traffic from specific hosts you don’t care about. Useful for filtering out CDN, analytics, or font loading traffic that clutters the view.

Find large JSON responses

content_type:json size:>50000

Finds JSON API responses larger than ~50KB. Unusually large responses might indicate an endpoint returning too much data (missing pagination, unnecessary fields), which is both a performance issue and potentially a security concern (information leakage).

Find failed requests with no response

has:error

Finds flows where the request failed entirely — connection refused, DNS resolution failure, timeout, TLS handshake error. These are often the most important flows to investigate, as they indicate something fundamentally broken.

Filter Presets

Ghost provides quick filter buttons below the search bar for the most common queries. Click any preset to instantly apply it — click it again to remove the filter:

Preset Button	What It Does	Equivalent GQL
API Only	Shows only JSON API responses, hiding HTML pages, images, scripts, and other asset types	content_type:json
Errors	Shows only flows with error status codes (4xx client errors and 5xx server errors)	status:>399
Slow	Shows requests that took more than 1 second to complete	duration:>1000
Has Interaction	Shows flows with correlated browser interactions	has:interaction

Presets can be combined — clicking “Errors” and “API Only” together shows only JSON API errors.

Structured Filters

In addition to typing GQL queries, the command bar provides visual filter controls that you can click:

• Method filter: A multi-select dropdown where you check the HTTP methods you want to see (GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD). Uncheck methods to hide them.
• Status filter: A multi-select with status code ranges (2xx success, 3xx redirect, 4xx client error, 5xx server error) or specific individual codes.
• Content type filter strip: A row of toggleable pills (API, Pages, JS, CSS, Images, Fonts, Media) that you can click to show/hide each content category.

Structured filters are combined with GQL queries using AND logic — a flow must match both the structured filters and the GQL query to appear in the list. This lets you use the visual filters for broad scoping (like “only show API traffic”) and GQL for specific searches within that scope.

Scope Filtering

The domain/app/device navigators in the left sidebar provide yet another layer of filtering:

• Domain scope: Click one or more hostnames in the domain navigator — the flow list shows only traffic to those hosts. Multi-select with Ctrl+Click.
• App scope: Switch to the app navigator and select a detected application — only that app’s traffic appears.
• Device scope: Select a connected mobile device — only traffic from that device appears.

Scope filters, structured filters, and GQL queries all combine together. For example, you could select api.hepsiburada.com in the domain navigator, click “Errors” preset, and type path:/checkout — showing only error responses from the checkout API on Hepsiburada’s API server.

AI Agent Usage

The AI agent uses GQL internally through the search_traffic tool. When you ask the agent something like “find all failed login attempts,” it translates your request into a GQL query:

{
  "tool": "search_traffic",
  "input": {
    "query": "method:POST path:/login status:>399",
    "limit": 50,
    "offset": 0
  }
}

The limit parameter controls how many results to return (to avoid overwhelming the agent with thousands of flows), and offset enables pagination through large result sets. The agent can also use free-text search to find specific content buried in request/response bodies — for example, searching for a specific error message or user ID.