---
title: Trending Queries API
description: Retrieve currently trending search queries using the Trending Queries API.
slug: autocomplete/api/v2/trending-queries
docKind: endpoint
hub: autocomplete
tableOfContents: true
---
import ApiSection from "../../../../../components/ApiSection.astro";
import ApiEndpoint from "../../../../../components/ApiEndpoint.astro";
import ApiCodeTabs from "../../../../../components/ApiCodeTabs.astro";
import { Tabs, TabItem } from "@astrojs/starlight/components";

<ApiSection>
  <div slot="code">
    <ApiEndpoint method="GET" url="https://live.luigisbox.com/v2/trending_queries" />
  </div>
## Overview

The Trending Queries API returns a list of search terms that are currently popular among your users. It is typically used to render a "Trending Searches" list before the user starts typing.
</ApiSection>

<ApiSection>
## Request parameters

### Required parameters

| Parameter | Type | Required | Description |
| :-- | :-- | :-- | :-- |
| `tracker_id` | string | ✓ | Your unique site identifier within Luigi's Box. |

### Optional parameters

| Parameter | Type | Description |
| :-- | :-- | :-- |
| `ctx[]` | string | Model-selection context in `key:value` format, for example `ctx[]=warehouse:berlin`. Keys must match contexts reported in [Analytics](/analytics/#concepts-context). |

### Request headers

| Header | Value | Required | Description |
| :-- | :-- | :-- | :-- |
| `Accept-Encoding` | `gzip, deflate` | Recommended | Enables compressed responses to reduce payload size. |

  <div slot="code">
    <h4 class="code-section-title">Example Request</h4>

```shell
curl "https://live.luigisbox.com/v2/trending_queries?tracker_id=YOUR_TRACKER_ID" \
  -H "Accept-Encoding: gzip, deflate"
```
  </div>
</ApiSection>

<ApiSection>
## How to Make a Request

To make a valid request:

1. Send a `GET` request to `https://live.luigisbox.com/v2/trending_queries`.
2. Provide `tracker_id`.
3. Add `ctx[]` only when you need model segmentation.

For implementation guidance, see [Quickstart: Trending Queries](/quickstart/autocomplete/trending-queries/).

  <div slot="code">
    <h4 class="code-section-title">Code Examples</h4>
    <ApiCodeTabs syncKey="trending-queries-request">
      <div slot="ruby">

```ruby
require 'faraday'
require 'json'

connection = Faraday.new(url: 'https://live.luigisbox.com') do |conn|
  conn.use FaradayMiddleware::Gzip
end

response = connection.get('/v2/trending_queries') do |req|
  req.params['tracker_id'] = 'your_tracker_id'
  req.headers['Accept-Encoding'] = 'gzip, deflate'
end

if response.success?
  puts JSON.pretty_generate(JSON.parse(response.body))
else
  puts "Error: HTTP Status #{response.status}, Response: #{response.body}"
end
```
      </div>
      <div slot="php">

```php
<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client();
$response = $client->request('GET', 'https://live.luigisbox.com/v2/trending_queries', [
    'query' => [
        'tracker_id' => 'your_tracker_id',
    ],
    'headers' => [
        'Accept-Encoding' => 'gzip, deflate',
    ],
]);

echo json_encode(json_decode($response->getBody()), JSON_PRETTY_PRINT);
```
      </div>
      <div slot="javascript">

```javascript
const axios = require('axios');

axios
  .get('https://live.luigisbox.com/v2/trending_queries', {
    params: {
      tracker_id: 'your_tracker_id',
    },
    headers: {
      'Accept-Encoding': 'gzip, deflate',
    },
  })
  .then((response) => {
    console.log(JSON.stringify(response.data, null, 2));
  })
  .catch((error) => {
    if (error.response) {
      console.error(`Error: HTTP Status ${error.response.status}`);
      console.error(JSON.stringify(error.response.data));
    } else {
      console.error(error.message);
    }
  });
```
      </div>
    </ApiCodeTabs>
  </div>
</ApiSection>

<ApiSection>
## Response structure

The response is a JSON array where each object represents one trending query.

### Response attributes

| Field | Type | Description |
| :-- | :-- | :-- |
| `[root]` | array | List of trending query objects. |
| `title` | string | Text of the trending query. |

  <div slot="code">
    <h4 class="code-section-title">Example Response</h4>

```json
[
  {
    "title": "get 10% off"
  },
  {
    "title": "guitar"
  },
  {
    "title": "testing"
  },
  {
    "title": "bass guitar"
  },
  {
    "title": "kalimba"
  },
  {
    "title": "digital piano"
  },
  {
    "title": "piano"
  },
  {
    "title": "black friday"
  }
]
```
  </div>
</ApiSection>

<ApiSection>
## Error handling

The API uses standard HTTP status codes to indicate success or failure.

| HTTP Status | Description |
| :-- | :-- |
| `200 OK` | The request succeeded and results are returned. |
| `400 Bad Request` | The request was malformed — missing or invalid `tracker_id`. |
| `500 Server Error` | Internal error. If persistent, contact support. |
| `504 Gateway Timeout` | The request took too long to process. Retrying may succeed. |

  <div slot="code">
    <h4 class="code-section-title">Error responses</h4>

<Tabs>
  <TabItem label="400 Bad Request">
```text
tracker_id parameter is missing
```
  </TabItem>
</Tabs>
  </div>
</ApiSection>