# head()

`head([n])` returns the first `n` rows from the input stream. `n` must be between 1 and 10,000 and defaults to 10.

When applied directly to a query filter, rows are ordered by timestamp (`@scnr.datetime`), and the first (oldest) rows are returned.

When applied after another aggregation (for example, `groupbycount ... | head 3`), the first rows in the order produced by that aggregation are returned.

If your query matches fewer than `n` rows, all matching rows are returned. The result may also be smaller than `n` rows if the total result size exceeds 128MB (or `max_bytes` if using the [API](https://docs.scanner.dev/scanner/using-scanner-complete-feature-reference/developer-tools/api/ad-hoc-queries)). In either case, the returned rows are always the true first rows — no earlier rows are omitted.

See also: [tail()](https://docs.scanner.dev/scanner/using-scanner-complete-feature-reference/querying-and-analysis/aggregation-functions/tail), which returns the last rows.

## Returns

A table with up to `n` rows, preserving all original columns.

## Examples

<pre class="language-python"><code class="lang-python"><strong># Get the 10 oldest error responses from the checkout_api service (default n)
</strong><strong>%ingest.source_type: "kubernetes"
</strong>and kubernetes.container_name: "checkout_api"
and status_code >= 400
| head

# Count distinct source IPs across the first 1,000 S3 API calls
%ingest.source_type: "aws:cloudtrail"
and eventSource: "s3.amazonaws.com"
| head 1000
| countdistinct sourceIPAddress

# Get the top 3 users by login count
eventName: "ConsoleLogin"
| groupbycount userIdentity.arn
| head 3
</code></pre>