# History and exports

URL: https://serpel.app/docs/history-and-exports

Updated: 2026-11-05

The History page lists everything Serpel runs for a project, from crawls and rank checks to syncs and report emails, so you can see what happened and fix what failed. Exports take your data out as CSV or JSON, from tables in the dashboard or through the API and CLI. Tasks, which turn audit issues into a to-do list that Serpel re-checks after each crawl, exist only in the API and CLI.

## What are history and exports in Serpel?

Almost everything Serpel does for you runs as a background job: a crawl, a rank check, a monitoring run, a sync. The **History** page is the log of those jobs, plus the report emails and keyword researches of the project. It answers three questions: did it run, did it work, and what do I do if it didn’t? Exports and tasks sit on the same page of the docs because they work with the same data: you export what the jobs produced and track what you fix.

**The life of a job**

1. **Queued**: The job waits for a worker, or for its scheduled time.
2. **Running**: The entry shows the current step, for example “Checking rankings”.
3. **Retry** (Automatic): After a temporary error, the worker waits and tries again.
4. **Finished** (Completed or failed): A result summary or the last error appears in the entry.

## What does the History page show?

**History** sits under **Activity** in the project sidebar. Two cards on top show **Jobs in 7 days** and **Failed**, with the types that failed and when. To the right, **By type** counts the entries per type. The main list groups entries by day, newest first, with 50 entries per page and **Newer** and **Older** buttons. Each entry shows its type, a status badge, the time, a one-line result and the duration. While a job is queued or running, the page refreshes every few seconds.

Click an entry to open its details: status, when it was queued, scheduled, started and finished, the duration, the attempts as “1 of 3” and, after failures, the error of every attempt. A finished monitoring run has a **View report** link. Viewers can read everything but can’t cancel or retry.

## Which entries appear and what do the statuses mean?

| Entry | What it records | Value in the CLI and API |
| --- | --- | --- |
| Crawl | A site crawl with its audit. | `crawl` |
| Rank check | A rank check that you start from **Tracked keywords**, the CLI or the API, outside a monitoring run. | `rank_check` |
| AI check | A check of your AI prompts outside a monitoring run. | `ai_check` |
| Monitoring | A monitoring run. Its entry links to the report (see [monitoring and reports](https://serpel.app/docs/monitoring-and-reports)). | `monitoring` |
| Search data sync | The daily Google Search Console sync. | `search_sync` |
| Web analytics sync | The daily sync of conversion data. | `analytics_sync` |
| Codebase snapshot | The processing of an uploaded codebase snapshot. | `codebase_snapshot` |
| Generate recommendations | A recalculation of opportunities, at most once every 60 minutes per project. | `recommendation_generate` |
| Bing index sync | The daily Bing Webmaster Tools sync. | `bing_sync` |
| Email report | A monitoring report sent to the recipients of the project. | Shown in the activity list only |
| Keyword research | A keyword research with its input and result count. | Shown in the activity list only |

**The five job statuses**

- **Active** (Queued and Running): Queued: waiting for a worker or for its scheduled time. Running: the entry shows progress. You can cancel both.
- **Done** (Completed): The entry summarises the result, for example “17 keywords checked, report written”. Partial failures are named in the summary.
- **Needs you** (Failed and Cancelled): Failed: the entry shows the last error. Cancelled: you or Serpel stopped the job. You can retry both.

The API and CLI use the values `queued`, `running`, `succeeded`, `failed`, `cancelled` for the same five statuses. The summary numbers on the page cover the last 7 days. In the API and CLI you can widen them up to 90 days with `days` or `--days`.

## How do you cancel or retry a job?

1. **Open the entry.** Click it in the list. Only owners and editors see the buttons.

2. **Press Cancel job or Retry.** **Cancel job** appears for queued and running jobs. A queued job stops at once, a running job stops at its next checkpoint and shows “Cancelling …” until then. **Retry** appears for failed and cancelled jobs and queues the same job again.

3. **Watch the entry.** A retried job starts with a fresh set of attempts. The toast says “Cancellation requested” or that the job is queued again.

Serpel also retries on its own. Each job gets up to three attempts in total. After a temporary error, such as a provider timeout, the worker waits about half a minute before the second attempt and about two minutes before the third. Errors that trying again can’t fix, such as a deleted project, fail at once. A job whose worker disappears is released and runs again within the same limit. If the last attempt fails, the job is **Failed** and waits for you.

## How long does Serpel keep history?

Finished jobs are removed after 180 days. Serpel keeps the newest finished job of each type and outcome per project, so the last result of every kind stays visible. Running and queued jobs are never removed. The saved results of a keyword research are emptied after 180 days as well.

## What can you export?

**Three ways to export**

- **Tables and lists** (CSV in the dashboard): **Options → Export as CSV** on a table. Exports the rows you currently see, with your filters and sort. Semicolon-separated, UTF-8 with byte order mark.
- **Project export** (API and CLI): Whole data sets of a project. Formats `csv`, `json`. Needs the scope `export:read`.
- **Account data** (JSON): Profile, workspace, projects and integrations. No credentials in the file. In **Settings**, under **Data and account**.

### Which tables have Export as CSV?

Open **Options** at the right end of the view bar and choose **Export as CSV** on **Tracked keywords**, **Opportunities**, the routes of the **Codebase** page, the audit **Pages** table and the list of URLs of one issue. The file is named after the table and the date, for example `tracked-keywords-2026-11-05.csv`. Two more lists have their own export: **Export** on [search data](https://serpel.app/docs/search-data) and [web analytics](https://serpel.app/docs/web-analytics) offers several files, and the command menu (Ctrl K) offers **Download issues as CSV** and **Download issues as JSON** on the **Issues** page, and **Download keyword ideas as CSV** and **Download keyword ideas as JSON** after a keyword research (see [keyword research](https://serpel.app/docs/keyword-research)).

### What does the project export contain?

| Type | What you get | Options |
| --- | --- | --- |
| `issues` | Every issue occurrence of a crawl with severity, code, title, URL, details, why it matters, the fix and when it was detected. | `--crawl <id>`, default is the last completed crawl |
| `keywords` | The keywords in your keyword lists with list name, volume, CPC, ads competition, difficulty, intent and topic group. | `--list <id>` for one keyword list |
| `rankings` | Every stored rank check: keyword, market, device, time, depth, position, result, ranking URL and provider. | Streamed, so large histories work |
| `tasks` | Title, status, priority, issue, linked URLs, description, re-check result and dates. | None |

The type is one of `issues`, `keywords`, `rankings`, `tasks`. The file is named `serpel_<domain>_<type>_<date>.csv` or `.json`. The CSV is comma-separated and starts with a byte order mark so Excel reads UTF-8 correctly. The JSON repeats the project, the type and the export time before the rows. Keyword lists also export through `GET /keyword-lists/{id}/export`, and the account data through `GET /account/export`.

## How do tasks work?

A task is an optimisation to-do for a project. There is no Tasks page in the dashboard, so you manage tasks with the [CLI](https://serpel.app/docs/cli) or the [REST API](https://serpel.app/docs/api). A task is either free (just a title) or created from an audit issue. An issue task carries the affected URLs of the latest completed crawl, uses the issue’s explanation and fix as its description and takes its priority from the severity: errors are High, warnings Medium and notices Low. There is only one open task per issue, so creating it twice returns the existing task.

The status is Open, In progress or Done. After every completed crawl, Serpel re-checks each task that was created from an issue, if it isn’t done or was completed in the last 90 days, against the new crawl. The result is **Resolved** when none of the linked URLs still has the issue, **Partially resolved** when some do and **Still present** when all do. The re-check never changes the status of a task: you decide when it is done. `serpel tasks show` lists the URLs that are still affected.

## How do you use history, exports and tasks from the CLI, API or MCP?

Reading jobs needs the scope of the job’s area, for example `audit:read` for crawls, `projects:read` for syncs and `rankings:read` for rank checks, AI checks and monitoring. Retrying needs the matching write scope. The activity list accepts any of the read scopes. Tasks need `tasks:read` and `tasks:write`.

```bash
serpel jobs activity --project "$PROJECT_ID" --days 30
serpel jobs list --project "$PROJECT_ID" --status failed
serpel jobs status "$JOB_ID" --wait
serpel jobs retry "$JOB_ID"
serpel jobs cancel "$JOB_ID"
serpel export --project "$PROJECT_ID" --type issues --format csv --output issues.csv
serpel export --project "$PROJECT_ID" --type rankings --format json --output rankings.json
serpel tasks create --project "$PROJECT_ID" --issue title_missing
serpel tasks update "$TASK_ID" --status done
serpel tasks show "$TASK_ID"
```

```bash
curl "https://serpel.app/api/v1/projects/$PROJECT_ID/activity?days=30&limit=50" \
  -H "Authorization: Bearer $SERPEL_TOKEN"

curl -X POST https://serpel.app/api/v1/jobs/$JOB_ID/retry \
  -H "Authorization: Bearer $SERPEL_TOKEN"

curl -o issues.csv "https://serpel.app/api/v1/projects/$PROJECT_ID/export?type=issues&format=csv" \
  -H "Authorization: Bearer $SERPEL_TOKEN"

curl -X POST https://serpel.app/api/v1/projects/$PROJECT_ID/tasks \
  -H "Authorization: Bearer $SERPEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"issueCode": "title_missing", "priority": "high"}'
```

With the CLI, `serpel jobs status` and the `--wait` flag of long commands poll a job for you and exit with a non-zero code when it fails. For AI assistants, the MCP tool `get_job_status` reports the status, progress, attempts and a summary of any job by ID and suggests polling every 10 to 30 seconds. There is no MCP tool for tasks or exports. `get_project_overview` includes the task counts. Setup is on the [MCP page for Claude Code](https://serpel.app/docs/mcp/claude-code).

## Where to go next

- [Monitoring and reports](https://serpel.app/docs/monitoring-and-reports): Schedule runs and read the reports they create.
- [Site audit](https://serpel.app/docs/site-audit): Crawl your site and turn issues into tasks.
- [Credits and billing](https://serpel.app/docs/credits-and-billing): See what jobs cost and how credits are charged.
- [Troubleshooting](https://serpel.app/docs/troubleshooting): Find the fix when a job fails.