Quickstart

From a new account to a finished run and an API call from your own server. This takes about five minutes.

1. Create an account and add credits

   Create an account. You become the owner of a new organization. Runs are prepaid, so open Billing and add credits; $10 is plenty to start.

   Credits appear as soon as Stripe confirms the payment, usually within seconds.

2. Start a run in the playground

   In the dashboard, open Playground and choose Try an example on the Runs page, or write your own prompt. Press ⌘↵ to start it. The output streams in on the right, next to every step the worker takes.

   Every run has a page with its output, a timeline of events, and what it cost.

3. Create an API key

   Open API keys and create a member key. It is shown once, with a snippet ready to paste into your environment. Keep it on your server.

   Terminal

   export EPHEMERAL_URL=https://app.ephemer.al
   export EPHEMERAL_API_KEY=eak_…

4. Start the same run from your code

   cURLNode.jsCLI

   curl $EPHEMERAL_URL/v1/runs \
     -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{
       "prompt": "Summarize the input in one sentence",
       "input": { "text": "The export finished but two invoices are missing." },
       "max_cost_micros": 500000
     }'

   The response is 202 Accepted with the run's id. The run is queued and starts as soon as a worker is free.

5. Get the result

   Poll GET /v1/runs/{id} until the status is final: succeeded, failed, cancelled, timed_out or interrupted. Then wait for billing_pending to be false, so the cost is settled. A successful run has its answer in output; any other final status explains itself in error.

   cURLNode.jsCLI

   RUN_ID=run_4abb0f420c6623a12d2889610eb67284   # the id from the previous step
   
   while true; do
     RUN=$(curl -sf "$EPHEMERAL_URL/v1/runs/$RUN_ID" \
       -H "Authorization: Bearer $EPHEMERAL_API_KEY") || exit 1
     case $(jq -r .status <<<"$RUN") in
       succeeded|failed|cancelled|timed_out|interrupted)
         [ "$(jq -r .billing_pending <<<"$RUN")" = false ] && break ;;
     esac
     sleep 2
   done
   
   jq '{status, output, error, cost_micros}' <<<"$RUN"

   A missing cost_micros means zero. With --wait the CLI returns as soon as the status is final, so read the run again with ephemeral runs get if you need the settled cost. You can also stream events from GET /v1/runs/{id}/events. For long runs, give the request a callback and Ephemeral calls you when it finishes, so nothing has to poll.

   The response of a finished run looks like this.

   GET /v1/runs/run_…

   {
     "id": "run_4abb0f420c6623a12d2889610eb67284",
     "status": "succeeded",
     "output": "Two invoices are missing from an otherwise complete export.",
     "cost_micros": 3120,
     "max_cost_micros": 500000,
     "billing_pending": false
   }

Next steps

• Run a real investigation with files, a connection and web access.
• Save the prompt as a workflow and start it by name.
• Give the run files to read and connections to call.
• Learn how budgets keep every run within a limit.