---
title: "Get articles with range faceting for timelines"
description: "Create histogram-style bucketed counts for building timelines and distribution charts"
source: https://apitube.io/cookbook/get-articles-with-range-faceting-for-timelines
---

#### Input parameters

| Parameter            | Description                                    | Type    | Default | Required |
|:---------------------|:-----------------------------------------------|:--------|:--------|:---------|
| facet.range          | Enable range faceting (set to true or 1).      | boolean |         | Yes      |
| facet.range.field    | Field to create ranges on.                     | string  |         | Yes      |
| facet.range.start    | Start value for the range.                     | string  |         | Yes      |
| facet.range.end      | End value for the range.                       | string  |         | Yes      |
| facet.range.gap      | Gap/interval between ranges (e.g., 1WEEK, 1DAY). | string  | 1DAY    | No       |
| api_key              | Your API key.                                  | string  |         | Yes      |
| per_page             | Maximum number of articles to retrieve.       | integer | 20      | No       |

#### Workflow examples

##### Request for date range faceting - articles per week:

```shell
curl -X GET "https://api.apitube.io/v1/news/everything?title=bitcoin&facet.range=true&facet.range.field=published_at&facet.range.start=2024-01-01&facet.range.end=2024-03-01&facet.range.gap=1WEEK&api_key=YOUR_API_KEY"
```

##### Request for sentiment distribution analysis:

```shell
curl -X GET "https://api.apitube.io/v1/news/everything?organization.name=Apple&facet.range=true&facet.range.field=sentiment.overall.score&facet.range.start=-1&facet.range.end=1&facet.range.gap=0.25&api_key=YOUR_API_KEY"
```

##### Request for reading time distribution:

```shell
curl -X GET "https://api.apitube.io/v1/news/everything?category.id=medtop:04000000&facet.range=true&facet.range.field=read_time&facet.range.start=0&facet.range.end=30&facet.range.gap=5&api_key=YOUR_API_KEY"
```

---

#### Related Examples

- [Get articles with faceting for analytics](/cookbook/get-articles-with-faceting-for-analytics)
- [Get long-read articles](/cookbook/get-long-read-articles)
- [Select specific fields](/cookbook/select-specific-fields-to-reduce-payload-size)
- [Get sorted news by date](/cookbook/get-sorted-news)
- [Get news in a specific time range](/cookbook/get-latest-news-articles-in-a-specific-time-range)