> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runorion.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Orion is a collaborative analytics platform built by Gravity (bygravity.com). It connects to data warehouses, to Looker and dbt for existing business logic, and to a small set of external-context sources, and it lets teams ask questions in natural language to get shared analyses, dashboards, reports, and slide decks. The Connecting Data Sources page is the authoritative list of supported sources. When referencing Orion features, always link to the relevant documentation page. Orion is not open-source; it is a commercial SaaS product accessed at runorion.com.
# Export a Project
> Download a project's definition as one TOML file
Any project can be exported as a single TOML file with its definition: settings, data source selections, Knowledge Base pages, metrics, notebooks, and Workflows. The file is plain text, and two exports of an unchanged project are identical, so a diff shows only real changes. Use it to keep projects under [version control](/version-control/sync-to-git) or to [import](/version-control/import) a project into another tenant.
## What the File Contains
| Section | Contents |
| - | - |
| `[project]` | Name, description, slug, and project settings |
| `[[groups]]` | The groups that have access to the project, by name. Grants only, not members |
| `[[datasource_selections]]` | Each connected data source by name and type, and which tables and fields the project uses. No connection details |
| `[[catalog_metrics]]` | Which tenant-level catalog metrics the project uses, and in which mode. The metric definitions themselves stay in the catalog |
| `[[wiki_pages]]` | Knowledge Base pages linked to the project: title, path, parent, tags, and full content |
| `[[metrics]]` | Metric definitions: description, visibility, value type, Python code, SQL sources with their data source, schedule, and dashboard card layout |
| `[[insight_makers]]` | Saved notebooks: cells, sources, parameters, metric references, schedule, and context instructions |
| `[[workflows]]` | Each Workflow's name, schedule, and its step definition, verbatim |
References between exported items use slugs derived from names. Workflow bodies retain embedded IDs and include reference maps used during import. Groups and catalog metrics also retain their IDs as external references. Cross-tenant imports depend on matching data sources and other existing dependencies; review the [import requirements](/version-control/import#what-must-already-exist) and warnings.
## What Is Not Included
* Outputs: run results, reports, slide decks, CSV exports, and podcasts
* Chat conversations, memories, and uploaded files
* Data source connections and credentials. A source is named by data source name and type only
* User identities, ownership, timestamps, and other audit fields
* Private and draft content. The file includes shared, published, or pinned metrics, published or template notebooks, and shared Workflows. A draft that a shared Workflow depends on is included so the Workflow can be re-imported in working order
## Who Can Export
Export needs admin capability on the project: a tenant Admin, the project owner, or a Group Admin of a group with access to the project. Analysts and Viewers do not see the option. See [Roles at a Glance](/configuration/groups#roles-at-a-glance).
## From the App
Go to **Projects**, hover over the project, and click the three-dot menu.
The same menu is available next to each project in the left-hand
navigation menu.
A dialog summarizes what the file will contain. Leave **Include run
history** off for a file meant for version control. Click **Export**. The
browser downloads `.dsl.toml`.
### Include run history
Turn this on to append what ran and whether it failed, for each metric, notebook, and Workflow. The file gains a `[meta]` block with the export time and a `history` list per item: run times, status, and error messages, no payloads. **Runs per item** caps each list, 50 by default and 500 at most.
The timestamp makes every export unique, so keep history off for version control. Files with history are for incident review and audit sampling. Import accepts them but drops the history.
## From the API
The export endpoint is the same one the app uses. Authenticate with a bearer token, then request the file.
### Get a token
Exchange a username and password for a token at the login endpoint. The token is valid for four weeks.
```bash theme={null}
export ORION_URL="https://your-tenant.runorion.com"
TOKEN=$(curl -sf -X POST "$ORION_URL/api/auth/login" \
--data-urlencode "username=$ORION_USER" \
--data-urlencode "password=$ORION_PASSWORD" | jq -r .access_token)
```
The password login endpoint requires a stored Orion password. An SSO-only
account without one cannot use this endpoint. Run this example as a
dedicated account with an Orion password. See [Export Orion Snapshots to
Git](/version-control/sync-to-git#prerequisites).
### Download the file
```bash theme={null}
curl -sf -H "Authorization: Bearer $TOKEN" \
"$ORION_URL/api/projects//dsl-export/" \
-o finance-kpis.dsl.toml
```
The project ID is the last segment of the project's URL in the app, `/projects/`.
Keep the trailing slash on `/dsl-export/`. A different path can return a
redirect instead of the TOML file; `curl -f` alone does not reject redirects.
| Query parameter | Default | Meaning |
| - | - | - |
| `include_history` | `false` | Also export run history. Adds a `[meta]` block with a timestamp |
| `history_limit` | `50` | Most recent runs kept per item when history is on. Between 1 and 500 |
The response body is the TOML document with content type `application/toml`. Two response headers are set:
* `Content-Disposition` gives the filename: the project name as a slug, plus `.dsl.toml`
* `X-Dsl-Export-Summary` counts what was left out or could not be resolved, for example `excluded_metrics=3` when three private metrics were skipped
| Status | Meaning |
| - | - |
| `401` | Missing, invalid, or expired token |
| `403` | The account does not have admin capability on this project |
| `404` | No project with that ID |
| `422` | `history_limit` outside 1 to 500 |
## Sample Export
An abridged export. SQL and Python are stored as multi-line strings, exactly as written, so a diff of this file shows query changes line by line.
```toml theme={null}
[project]
slug = "finance-kpis"
name = "Finance KPIs"
description = "Monthly close metrics for the finance team"
[[datasource_selections]]
datasource = "Snowflake Production"
datasource_type = "snowflake"
snapshot_version = 3
[[metrics]]
slug = "net-revenue"
name = "Net Revenue"
description = "Net revenue for the trailing 30 days"
visibility = "shared"
state = "active"
is_pinned = true
value_type = "number"
schedule_enabled = true
schedule_cron = "0 6 * * *"
python_code = """
result = round(float(df["net_revenue"].iloc[0]), 2)
"""
[[metrics.sources]]
variable_name = "df"
source_type = "query"
execution_order = 0
datasource = "Snowflake Production"
datasource_type = "snowflake"
[metrics.sources.query_config]
query = """
SELECT SUM(amount) AS net_revenue
FROM finance.revenue
WHERE booked_at >= DATEADD(day, -30, CURRENT_DATE)
"""
[[workflows]]
slug = "monthly-close-digest"
name = "Monthly Close Digest"
visibility = "shared_board"
schedule_enabled = true
schedule_cron = "0 8 1 * *"
schema_version = "1.0"
toml = """
schema_version = "1.0"
[[steps.metrics]]
id = "net-revenue"
metric_id = "2f1c9c2e-3b6d-4d7a-9a1e-6c1f4d2b8e10"
[[steps.reports]]
id = "close-summary"
format = "markdown"
[steps.reports.recipe]
metric_ids = ["2f1c9c2e-3b6d-4d7a-9a1e-6c1f4d2b8e10"]
"""
[workflows.refs.metrics]
"2f1c9c2e-3b6d-4d7a-9a1e-6c1f4d2b8e10" = "net-revenue"
```
The Workflow body keeps the IDs it was saved with, and the `refs` table maps each one to a slug in the same file. Import uses that map to connect the Workflow to the metrics it recreates.
## Next Steps
Schedule snapshots and review exported differences in pull requests
Create a project from a committed file
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.