# What Is the Nitter Function Responsible for Searching Tweets?

> Discover the Nitter function getGraphTweetSearch in src/api.nim that handles tweet searches, query construction, and response parsing. Learn how Nitter searches tweets.

- Repository: [Zed/nitter](https://github.com/zedeus/nitter)
- Tags: deep-dive
- Published: 2026-08-29

---

**The `getGraphTweetSearch` procedure defined in `src/api.nim` is the core Nitter function responsible for searching tweets, handling GraphQL query construction, HTTP request execution, and response parsing.**

Nitter is a free and open-source alternative Twitter front-end that proxies user requests to Twitter's internal API. When users search for tweets, the request flows through a specific async function that bridges the web router and Twitter's GraphQL search endpoints. Understanding this function reveals how Nitter translates simple HTTP queries into structured timeline results.

## The Core Search Function: getGraphTweetSearch

The definitive entry point for tweet searches lives in `src/api.nim` as the `getGraphTweetSearch` procedure. This async function accepts a `Query` object and an optional pagination cursor, constructs the GraphQL payload, executes the HTTP request, and returns a `Timeline` object containing the matching tweets.

The function signature demonstrates its async nature and type-safe design:

```nim
proc getGraphTweetSearch*(query: Query; after=""): Future[Timeline] {.async.}

```

Inside the implementation, `getGraphTweetSearch` performs four critical steps. First, it generates query parameters via `genQueryParam(query, maxId)`. Second, it constructs the Twitter API URL using `apiReq(graphSearchTimeline, $variables)`, where `graphSearchTimeline` represents the specific GraphQL endpoint identifier. Third, it fetches data asynchronously through `fetch(url)`. Finally, it parses the JSON response using `parseGraphSearch[Tweets](js, after)` and attaches the original query metadata to the result object before returning.

## HTTP Route Handling and Request Flow

While `getGraphTweetSearch` manages backend communication, user requests enter the system through `createSearchRouter` in `src/routes/search.nim`. This router handles GET requests to `/search` and delegates tweet-specific queries to the API function.

When a request hits the endpoint with `f=tweets` (or defaults to tweet search), the router logic at approximately line 50 invokes the search function:

```nim

# src/routes/search.nim

let tweets = await getGraphTweetSearch(query, getCursor())
resp renderMain(renderTweetSearch(tweets, prefs, getPath()),
                request, cfg, prefs, title, rss=rss)

```

This code illustrates the complete request lifecycle. The router parses HTTP parameters into a typed `Query` object, awaits the async search completion, and passes the `Timeline` result to `renderTweetSearch` for HTML generation. The `getCursor()` function extracts pagination tokens from the request to support infinite scrolling.

## Query Construction and Rendering Pipeline

The search ecosystem relies on two additional components that interact with `getGraphTweetSearch`. The `Query` type, defined in `src/query.nim`, structures user input including keywords, filters, time ranges, and exclusion criteria. This typed encapsulation ensures safe parameter transmission between the router and the API layer.

After the API function returns data, the rendering pipeline transforms raw JSON into user-facing HTML. The `renderTweetSearch` procedure generates the search results page, while `renderMain` (defined in the view layer) wraps this content with site navigation, preferences, and RSS feed links. The view templates, primarily located in `src/views/search.nim`, handle displaying tweet cards, media attachments, and pagination controls based on the `Timeline` data structure.

## Example Search Request Flow

Consider a typical user searching for "nim language":

```http
GET /search?f=tweets&q=nim+language HTTP/1.1
Host: nitter.net

```

The `createSearchRouter` transforms this request into a `Query` object and invokes `getGraphTweetSearch`. The function constructs a GraphQL request to the `graphSearchTimeline` endpoint, parses the response into a `Timeline`, and the router subsequently renders the results through the view layer. This architecture separates concerns cleanly between HTTP handling, API communication, and presentation logic.

## Summary

- **`getGraphTweetSearch`** in `src/api.nim` serves as the primary async function that executes tweet searches against Twitter's GraphQL API and returns a `Timeline` object.
- **`createSearchRouter`** in `src/routes/search.nim` handles HTTP routing for `/search` endpoints and invokes the search function when processing tweet queries.
- The **Query** type from `src/query.nim` structures search parameters including keywords, filters, and cursors for type-safe handling.
- **Rendering** occurs through `renderTweetSearch` and `renderMain`, which convert the API response into the final HTML interface.
- The function uses Nim's `async`/`await` pattern to handle concurrent search requests without blocking the main thread.

## Frequently Asked Questions

### What file contains the main Nitter function for searching tweets?

The main function is `getGraphTweetSearch`, located in `src/api.nim`. This procedure manages the entire search workflow including GraphQL query construction, HTTP request execution to Twitter's internal API, and JSON response parsing into a `Timeline` object.

### Is getGraphTweetSearch an asynchronous function?

Yes, `getGraphTweetSearch` is declared with the `{.async.}` pragma and returns a `Future[Timeline]`. This asynchronous design allows Nitter to handle multiple concurrent search requests efficiently while waiting for Twitter's API responses.

### How does Nitter structure search queries before sending them to Twitter?

Nitter uses the `Query` object defined in `src/query.nim` to encapsulate search parameters. The internal `genQueryParam` function converts this typed object into the variable format required by Twitter's GraphQL endpoint, handling pagination through the optional `after` parameter.

### Which HTTP route triggers the tweet search functionality?

The `createSearchRouter` procedure in `src/routes/search.nim` defines the `/search` route. When requests specify `f=tweets` or default to tweet search mode, the router calls `getGraphTweetSearch` and renders results using the `renderTweetSearch` view function.