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

# Ephemeris Push Task

> Schedule automated ephemeris uploads to external space catalogs (Space-Track, EU-SST)

> For the complete documentation index, see [llms.txt](/llms.txt).

An **Ephemeris Push** task automatically generates a fresh orbit ephemeris (OEM) for each of your spacecraft and uploads it to one or more external space catalogs on a schedule — so you never have to export and upload ephemeris files by hand.

**Route:** `/tasks`

## Overview

Operators with a standing obligation to keep external catalogs supplied with current ephemeris — for example [Space-Track](https://www.space-track.org) or the EU Space Surveillance & Tracking (EU-SST) network — can configure one Ephemeris Push task and leave it running. On every scheduled run, Valar:

1. Generates a current CCSDS Orbit Ephemeris Message (OEM) for each configured spacecraft, and
2. Uploads it to each configured catalog.

Each upload is tracked as an individual **delivery leg** (one per spacecraft-and-catalog pair), so you can see exactly what was delivered, what was skipped, and why.

Use an Ephemeris Push task when you need external catalogs to stay current automatically, without manual exports or uploads.

## Prerequisites

Before a spacecraft will be delivered on a run, it must meet a few conditions. Spacecraft that don't yet qualify are **skipped** (not failed) — the task keeps delivering for every other eligible spacecraft, and skipped spacecraft resume automatically once they qualify.

* **A NORAD ID.** The spacecraft must have a NORAD catalog ID configured on its Spacecraft page. Without one it is skipped with `NO_NORAD_ID`.
* **Current orbit data.** The spacecraft's orbit must be fresh enough to publish. Stale or degraded orbits are skipped (`ORBIT_STALE` / `ORBIT_DEGRADED`) until newer orbit data is available.
* **An active push clearance.** Each spacecraft-and-catalog pair must have an approved push clearance before Valar will upload on its behalf (see [Push clearance](#push-clearance) below).

<Note>
  Space-Track and EU-SST credentials are configured centrally by your administrator — you do not enter any catalog credentials when creating a task.
</Note>

## Setting up a task

<Steps>
  <Step title="Open the Tasks page">
    Go to **Tasks** (`/tasks`) and select **Create Task**.
  </Step>

  <Step title="Choose the Ephemeris Push type">
    In the task-type picker, select **Ephemeris Push**.
  </Step>

  <Step title="Select spacecraft">
    Choose one or more spacecraft to push ephemeris for. A spacecraft with no NORAD ID shows a **No NORAD ID** warning — you can still include it, but it will be skipped on each run until a NORAD ID is assigned.
  </Step>

  <Step title="Choose catalogs">
    Select one or more delivery targets: **Space-Track** and/or **EU-SST**.
  </Step>

  <Step title="Set the delivery cadence">
    Enter a schedule interval using the shorthand grammar (`6h`, `12h`, `1d`, `1w`). The **minimum is 6 hours**; the **default is daily** (`1d`). An interval below 6 hours is rejected with the inline error *"Schedule interval must be at least 6 hours."*
  </Step>

  <Step title="Review and create">
    Review your spacecraft, catalogs, and cadence, then create the task. It begins running on the schedule you set.
  </Step>
</Steps>

The task's overall run is reported as **succeeded** even when some spacecraft are skipped — a run only **fails** on a systemic fault (for example, a catalog is unreachable). Per-spacecraft skips never fail the run.

## Reading delivery-leg outcomes

Open the delivery-legs view for any Ephemeris Push run to see one row per delivery leg. Legs are ordered by severity — failed first, then skipped, then delivered. Each leg carries a colour-coded **outcome badge**:

| Code                         | Badge | Meaning                                                               | What to do                                                                             |
| ---------------------------- | ----- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `SUCCEEDED`                  | Green | Ephemeris was uploaded to the catalog successfully.                   | Nothing — this delivery is complete.                                                   |
| `NO_NORAD_ID`                | Amber | The spacecraft has no NORAD ID, which Space-Track requires.           | Add a NORAD ID on the spacecraft's Spacecraft page. Delivery resumes automatically.    |
| `ORBIT_STALE`                | Amber | The orbit is too old to publish.                                      | Refresh the orbit (run orbit determination or import a newer TLE) before the next run. |
| `ORBIT_DEGRADED`             | Amber | The orbit is in a degraded state.                                     | Confirm the orbit is acceptable or refresh it before the next run.                     |
| `NO_CLEARANCE`               | Amber | No active push clearance exists for this spacecraft and catalog.      | Contact Valar to arrange a push clearance (see [Push clearance](#push-clearance)).     |
| `CLEARANCE_PENDING_APPROVAL` | Amber | A push clearance has been granted but is awaiting four-eyes approval. | No action — delivery resumes automatically once the clearance is approved.             |
| `HALTED`                     | Amber | Uploads to this catalog are currently halted by an administrator.     | Contact support; deliveries resume when the halt is lifted.                            |
| `OEM_GENERATION_FAILED`      | Red   | The ephemeris file could not be generated.                            | Check the spacecraft's orbit data quality; contact support if it persists.             |
| `UPLOAD_HTTP_ERROR`          | Red   | The catalog rejected the upload.                                      | Contact support — this usually indicates a catalog-side or credential issue.           |
| `UPLOAD_IO_ERROR`            | Red   | A network error occurred during upload.                               | None — this is transient and is retried on the next scheduled run.                     |

When one or more legs are skipped for a clearance reason, an **informational note** appears beneath the table explaining why (pending approval, or no active clearance). This note is informational only — see below for how clearances are arranged.

## Push clearance

To protect against unauthorized disclosure of orbital data to external parties, Valar requires a **push clearance** for each spacecraft-and-catalog pair before any upload occurs. A spacecraft with no active clearance for a catalog is skipped on every run (`NO_CLEARANCE`) — no upload is attempted.

Clearances are governed by a **four-eyes** process:

* A **Valar platform administrator grants** a clearance for a specific spacecraft and catalog.
* **Two distinct authorized people must each approve** it before it becomes active. The same person cannot approve twice.
* Once both approvals are in, the clearance is **active**, and the next scheduled run will attempt the upload for that catalog.
* A clearance can be **revoked** at any time by an organization administrator or a Valar platform administrator.

In the delivery-legs view you can see the clearance-related status of your deliveries — `CLEARANCE_PENDING_APPROVAL` while a clearance is awaiting its approvals, or `NO_CLEARANCE` when none has been granted yet. **To arrange a new push clearance, contact Valar.** Every clearance change (grant, approval, revocation, denial) is recorded in a permanent audit log.

<Note>
  Delivery resumes automatically once a clearance becomes active — you do not need to re-trigger the task. A run that happens while a clearance is still pending simply logs a `CLEARANCE_PENDING_APPROVAL` leg and continues delivering for every other eligible spacecraft.
</Note>

## Scheduling notes

* The **minimum** delivery cadence is **6 hours**; the **default** is **daily** (`1d`).
* The task runs unattended on its schedule. A manual run is available from the task itself.
* Skips are self-healing: a spacecraft skipped for a missing NORAD ID, a stale orbit, or a pending clearance resumes delivery on the first run after the underlying condition is resolved — no manual re-trigger needed.