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

# End-to-End API Workflow

> Authenticate, list machines, submit a run, and stream the result over the REST API

This walks through a full API workflow with `curl` and `jq`. Replace `$LYCEUM_API_KEY` with an API key from [API Keys](/docs/configuration/api-keys).

```bash theme={null}
export LYCEUM_API_KEY="lk_..."
export BASE="https://api.lyceum.technology/api/v2/external"
```

## 1. Verify the key works

```bash theme={null}
curl -s "$BASE/billing/credits" \
  -H "Authorization: Bearer $LYCEUM_API_KEY" | jq
```

## 2. List the hardware profiles you can use

```bash theme={null}
curl -s "$BASE/user/quotas/available-hardware" \
  -H "Authorization: Bearer $LYCEUM_API_KEY" | jq
```

For pricing too:

```bash theme={null}
curl -s "$BASE/machine-types" \
  -H "Authorization: Bearer $LYCEUM_API_KEY" | jq
```

## 3. Submit a run

```bash theme={null}
EXEC=$(curl -s -X POST "$BASE/execution/streaming/start" \
  -H "Authorization: Bearer $LYCEUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "import sys; print(sys.version)",
    "machine_type": "cpu"
  }' | jq -r .execution_id)

echo "execution: $EXEC"
```

## 4. Poll status until done

```bash theme={null}
while :; do
  STATUS=$(curl -s "$BASE/execution/streaming/$EXEC/status" \
    -H "Authorization: Bearer $LYCEUM_API_KEY" | jq -r .status)
  echo "$STATUS"
  case "$STATUS" in
    completed|failed|aborted|cancelled|system_failure) break ;;
  esac
  sleep 2
done
```

## 5. Fetch the full record

```bash theme={null}
curl -s "$BASE/execution/$EXEC" \
  -H "Authorization: Bearer $LYCEUM_API_KEY" | jq
```

## 6. Fetch logs

```bash theme={null}
curl -s "$BASE/logs/execution/$EXEC" \
  -H "Authorization: Bearer $LYCEUM_API_KEY" | jq
```

## 7. Fetch GPU metrics

For GPU runs, per-execution GPU and system metrics are available:

```bash theme={null}
curl -s "$BASE/execution/$EXEC/metrics?step=15s" \
  -H "Authorization: Bearer $LYCEUM_API_KEY" | jq
```

## 8. Aborting a run

```bash theme={null}
curl -X POST "$BASE/execution/streaming/abort/$EXEC" \
  -H "Authorization: Bearer $LYCEUM_API_KEY"
```

Use `/execution/image/abort/...` for Docker runs and `/execution/compose/abort/...` for Compose stacks.