# What Do the QueryStatus Enum Values Mean in Sherlock? A Complete Guide

> Understand Sherlock QueryStatus enum values like CLAIMED, AVAILABLE, UNKNOWN, ILLEGAL, and WAF. Get a complete guide to username probe outcomes for deterministic reporting.

- Repository: [Sherlock/sherlock](https://github.com/sherlock-project/sherlock)
- Tags: api-reference
- Published: 2026-03-02

---

**Sherlock's `QueryStatus` enumeration defines five mutually exclusive states—CLAIMED, AVAILABLE, UNKNOWN, ILLEGAL, and WAF—that classify every username probe outcome, ensuring deterministic reporting across the tool's CLI and data exports.**

When probing hundreds of social networks for username availability, Sherlock needs a strict classification system to interpret HTTP responses consistently. The `QueryStatus` enum values, defined in [`sherlock_project/result.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/result.py), serve as the single source of truth for categorizing each site query. These five enum values capture every possible outcome, from successful detection to firewall blocks, enabling reliable data processing throughout the `sherlock-project/sherlock` codebase.

## Overview of the QueryStatus Enumeration

The `QueryStatus` class inherits from Python's standard `Enum` and lives in [`sherlock_project/result.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/result.py). It provides five mutually exclusive states that cover the entire spectrum of query outcomes:

```python
class QueryStatus(Enum):
    CLAIMED   = "Claimed"   # Username Detected

    AVAILABLE = "Available" # Username Not Detected

    UNKNOWN   = "Unknown"   # Error Occurred While Trying To Detect Username

    ILLEGAL   = "Illegal"   # Username Not Allowable For This Site

    WAF       = "WAF"       # Request blocked by WAF (i.e. Cloudflare)

```

Each value represents an architectural intent for how the result should propagate through the scanning pipeline and final report generation.

## Detailed Breakdown of Each QueryStatus Value

### CLAIMED – Username Detected

The **CLAIMED** status indicates that Sherlock found conclusive evidence the username exists on the target site. This typically triggers on HTTP 200 responses containing profile-specific patterns, confirmed profile URLs, or site-specific "user found" cues. In [`sherlock_project/sherlock.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/sherlock.py), this status is assigned after successful pattern matching against the response body or status code. The value propagates to the `QueryResult` object and ultimately appears in JSON/CSV exports as a confirmed claim.

### AVAILABLE – Username Not Detected

When a site returns a 404 status, "username available" message, or lacks any profile indicators, Sherlock assigns the **AVAILABLE** status. This definitive negative result tells users the handle is unclaimed on that specific platform. The [`sherlock_project/notify.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/notify.py) module uses this status to print availability messages and color-code CLI output accordingly.

### UNKNOWN – Error Occurred

The **UNKNOWN** status serves as both the default initialization value and the catch-all for unexpected failures. Before any HTTP request executes, [`sherlock_project/sherlock.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/sherlock.py) initializes `query_status = QueryStatus.UNKNOWN`. If network timeouts, parsing exceptions, or unhandled HTTP codes occur, the status remains UNKNOWN. This alerts users that the site could not be verified rather than falsely claiming availability or ownership.

### ILLEGAL – Username Not Allowable

Sherlock validates usernames against site-specific regex patterns before issuing HTTP requests. When a handle contains illegal characters, violates length restrictions, or otherwise fails validation for a particular site, the **ILLEGAL** status is assigned immediately. This pre-emptive check in [`sherlock_project/sherlock.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/sherlock.py) prevents unnecessary network traffic and eliminates false positives from malformed queries.

### WAF – Request Blocked by Web Application Firewall

The **WAF** status indicates the request was intercepted by a protective layer such as Cloudflare or another Web Application Firewall. Sherlock detects this by matching response headers or body content against known WAF signatures, typically accompanying HTTP 403 or 503 codes. Unlike UNKNOWN, this specific status informs users that the site actively blocks automated probing rather than experiencing a technical error.

## How QueryStatus Is Assigned in the Source Code

The core logic in [`sherlock_project/sherlock.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/sherlock.py) determines which status applies through a cascading decision tree:

```python

# Determine status after performing the HTTP request / pattern matching

if illegal_handle:
    query_status = QueryStatus.ILLEGAL
elif request_blocked_by_waf:
    query_status = QueryStatus.WAF
elif username_found:
    query_status = QueryStatus.CLAIMED
elif username_not_found:
    query_status = QueryStatus.AVAILABLE
else:
    query_status = QueryStatus.UNKNOWN

# Store the result for later aggregation

result = QueryResult(username, site_name, url, query_status, elapsed)
results[site_name] = {"status": result}

```

This exhaustive branching guarantees every site query maps to exactly one enum value, creating deterministic output for downstream consumers.

## Working with QueryStatus in Practice

Developers extending Sherlock can instantiate `QueryResult` objects directly using these enum values:

```python
from sherlock_project.result import QueryResult, QueryStatus

result = QueryResult(
    username="alice",
    site_name="Twitter",
    site_url_user="https://twitter.com/alice",
    status=QueryStatus.CLAIMED,
    query_time=0.42,
)
print(str(result))          # → Claimed

print(result.status)       # → QueryStatus.CLAIMED

```

The notification module ([`sherlock_project/notify.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/notify.py)) translates these states into human-readable messages:

```python
if result.status == QueryStatus.CLAIMED:
    logger.info(f"[+] {site} – {username} is CLAIMED")
elif result.status == QueryStatus.AVAILABLE:
    logger.info(f"[-] {site} – {username} is AVAILABLE")
elif result.status == QueryStatus.ILLEGAL:
    logger.warning(f"[!] {site} – {username} is ILLEGAL")
elif result.status == QueryStatus.WAF:
    logger.warning(f"[!] {site} – Request blocked by WAF")
else:  # UNKNOWN

    logger.error(f"[?] {site} – Could not determine status")

```

## Summary

- **CLAIMED** confirms username existence through positive HTTP response patterns detected in [`sherlock_project/sherlock.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/sherlock.py).
- **AVAILABLE** indicates the username is unclaimed on the target platform, typically following 404 responses.
- **UNKNOWN** represents indeterminate results due to errors or timeouts, serving as the safe default initialization.
- **ILLEGAL** flags usernames violating site-specific format constraints before any network request occurs.
- **WAF** identifies requests blocked by protective firewalls like Cloudflare, distinguishing active blocking from technical failures.

These five `QueryStatus` enum values form an exhaustive classification system defined in [`sherlock_project/result.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/result.py), processed in [`sherlock_project/sherlock.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/sherlock.py), and rendered through [`sherlock_project/notify.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/notify.py).

## Frequently Asked Questions

### What is the default QueryStatus value before Sherlock makes a request?

Before any HTTP request or validation check occurs, the code initializes `query_status = QueryStatus.UNKNOWN` in [`sherlock_project/sherlock.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/sherlock.py). This default ensures that if the program crashes or encounters an unhandled exception, the result clearly indicates an indeterminate state rather than a false positive or negative.

### How does Sherlock detect WAF blocks versus regular errors?

Sherlock distinguishes **WAF** from **UNKNOWN** by pattern matching response headers and body content against known Web Application Firewall signatures, such as Cloudflare challenge pages or specific 403/503 response patterns. While UNKNOWN covers general network or parsing failures, WAF specifically indicates the site actively blocked automated access.

### Can I add custom QueryStatus values to Sherlock?

While the `QueryStatus` enum in [`sherlock_project/result.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/result.py) can technically be extended, the five existing values are architecturally exhaustive for the current scanning pipeline. Adding new states would require modifications to the decision logic in [`sherlock_project/sherlock.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/sherlock.py) and the notification handlers in [`sherlock_project/notify.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/notify.py) to maintain consistent reporting across the entire tool.

### Where does Sherlock validate usernames for the ILLEGAL status?

Username validation against site-specific regex patterns occurs early in the scanning loop within [`sherlock_project/sherlock.py`](https://github.com/sherlock-project/sherlock/blob/main/sherlock_project/sherlock.py). If a handle fails to match the site's allowable character set or length requirements, the code immediately sets `query_status = QueryStatus.ILLEGAL` and skips the HTTP request entirely, optimizing performance and accuracy.