---
title: Retrieving data
description: The three ways to read recorded activity — timeline, query, and export — and how to choose between them.
---

Everything Tadoru records can be read back in three shapes. Pick by consumer:

| Command | Shape | Best for |
| --- | --- | --- |
| [`timeline`](#timeline--llm-ready-summaries) | Session-structured summary, token-budgeted | Feeding an LLM/agent. **The command agents call most.** |
| [`query`](#query--raw-events) | Raw events, filtered | Precise lookups, debugging, custom processing |
| [`export`](#export--bulk-dumps) | Raw events, everything in range | Backups, external pipelines |

## Time expressions

`--since` / `--until` accept:

| Form | Example | Meaning |
| --- | --- | --- |
| Relative | `15m` `2h` `1d` `1w` | Looking back from now; units are `s` `m` `h` `d` `w` |
| Absolute | `2026-08-16T09:00:00Z` | RFC3339 timestamp |
| Keyword | `now` | The current moment (mainly for `--until`) |

`--until` defaults to `now`. `--since` defaults per command: `timeline` = `1h`, `query` = `15m`, `export` = `24h`.

## `timeline` — LLM-ready summaries

Raw events are split into sessions, deduplicated, coalesced, and serialized to fit a token budget:

```bash
tadoru timeline --since 1h                             # Markdown, ~4000 tokens
tadoru timeline --since 30m --format json --granularity fine
tadoru timeline --since 1d --token-budget 8000
```

| Flag | Description |
| --- | --- |
| `--since` / `--until` | Range (default `--since 1h`) |
| `--format` | `md` (default, LLM-ready Markdown) or `json` (structured) |
| `--token-budget <N>` | Approximate token cap (default 4000). Content is coarsened to fit |
| `--granularity` | `coarse` (default, per session) or `fine` (down to individual interactions) |

With `--format json` you get the structured form:

```json
{
  "range": { "since": "2026-08-16T08:00:00Z", "until": "2026-08-16T09:00:00Z" },
  "token_estimate": 3810,
  "truncated": false,
  "sessions": [
    {
      "start": "2026-08-16T08:12:00Z", "end": "2026-08-16T08:31:00Z",
      "app": "Safari", "title_summary": "Reviewing PR #42",
      "activities": ["Viewed 3 files on GitHub", "Wrote 2 comments"],
      "event_ids": ["evt_01J...", "evt_01J..."]
    }
  ]
}
```

`event_ids` link each session back to the raw events behind it, so a consumer can drill down with `query`.

## `query` — raw events

```bash
tadoru query --since 15m --types browser.navigate,app.activate
tadoru query --since 2h --app Safari --format json --limit 500
tadoru query --since 1d --bundle-id com.google.Chrome --types "browser.*"
```

| Flag | Description |
| --- | --- |
| `--since` / `--until` | Range (default `--since 15m`) |
| `--types` | Comma-separated [event types](/reference/events); trailing wildcard like `browser.*` allowed |
| `--app` / `--bundle-id` | Filter by app name / bundle ID |
| `--limit <N>` | Max events (default 500) |
| `--format` | `jsonl` (default) / `json` / `table` |

These flags are **query-time filters** — they narrow what you read, not what gets recorded. For the recording-side boundary, see [filters](/guides/filters).

## `export` — bulk dumps

```bash
tadoru export --since 24h --format jsonl --out dump.jsonl
```

Dumps every raw event in range, for backups or external processing. Default range is `--since 24h`.

## Recipes

Restore context when resuming work (the one-liner shipped in skill files; the token budget stays at its default of 4000):

```bash
tadoru timeline --since 2h --format md
```

Let an agent check whether recording is even on:

```bash
tadoru status --json
```

Pull only what you did in Chrome today:

```bash
tadoru query --since 1d --app "Google Chrome" --types browser.navigate --format json
```