> ## Documentation Index
> Fetch the complete documentation index at: https://docs.factagora.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Timeseries

> Best practices for Timeseries

## Works with any time-based content

Timeseries organizes content chronologically, it works on both event-based content (news articles, reports, announcements) and structured data pages. Each data point captures what happened at a specific point in time as a text description, not a numeric value.

```json theme={null}
{ "timestamp": "2023-03", "label": "Italy temporarily bans ChatGPT over privacy concerns" }
{ "timestamp": "2024-08", "label": "EU AI Act enters into force" }
```

## Timestamps are pre-normalized

Timestamps are always returned in one of three formats: `YYYY`, `YYYY-MM`, or `YYYY-MM-DD`. You can sort and compare them safely as strings.

```javascript theme={null}
// Timestamps are already normalized, no conversion needed
dataPoints.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
```

## Use URLs pointing to content-rich pages

URLs pointing to articles, reports, or data pages with clear time-based information yield the best results. Sparse or navigation-only pages may return fewer data points.

```json theme={null}
{ "url": "https://en.wikipedia.org/wiki/Timeline_of_artificial_intelligence" }
```

## Use the file endpoint for PDFs and reports

For annual reports, whitepapers, or research documents, upload the file directly with the `/api/v1/timeseries/file` endpoint rather than passing a URL.

```bash theme={null}
curl -X POST "https://api.factagora.com/api/v1/timeseries/file" \
  -H "Authorization: Bearer fag_your_api_key" \
  -F "file=@annual-report-2024.pdf"
```

## Combine with Causality Graph

After extracting a timeseries, use [Causality Graph](/api-reference/causality-graph) to understand the causal relationships behind the sequence of events.

```
Timeseries (event sequence) → Causality Graph (why did each event happen?)
```