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

# Quickstart: Send Your First Request to Caveman Cloud

> Get from zero to a live trace in Caveman Cloud in a few minutes: sign in, create a project and API key, configure your client, send a request, and view it in Traces.

This guide takes you from signing in to viewing your first trace in the Caveman Cloud console. You need an existing upstream model provider account (for example OpenAI) with an API key.

<Tip>
  **Fastest path: let your coding agent do it.** In the console, open **Getting Started**, then **Send one request**, and choose the option where your coding agent does the wiring. Caveman Cloud gives you a prompt with your gateway URL and a fresh Cave key to paste into your agent. See [Connect your coding agent](/guides/connect-coding-agent) and [Automated AI setup](/guides/ai-setup). The manual steps below are the alternative.
</Tip>

<Steps>
  <Step title="Sign in to the console">
    Open your Caveman Cloud console in a browser and sign in. Invited members land directly in the project they were invited to.
  </Step>

  <Step title="Create a project">
    From the console, create a new project and name it. The project is the scope for all traces, keys, and workloads you will inspect.
  </Step>

  <Step title="Create a Cave API key">
    Go to **Gateway, Connect** and generate a Cave API key. Copy the key value and the gateway URL. The gateway URL is the origin for your installation, with no trailing slash. For example: `https://gateway.caveman.so`.

    <Note>
      Keep the Cave API key secret. It authenticates you to Caveman Cloud. It is separate from your upstream provider key.
    </Note>
  </Step>

  <Step title="Set environment variables">
    Export the key and gateway URL in your shell. Keep your upstream provider key available separately.

    ```bash theme={null}
    export CAVE_API_KEY="cave_live_..."
    export CAVE_GATEWAY_URL="https://gateway.caveman.so"
    export OPENAI_API_KEY="sk-..."
    ```
  </Step>

  <Step title="Configure your client">
    Point your OpenAI client at the gateway with a base-URL swap. Send the upstream provider key in the `x-cave-upstream-key` header when it is not stored in Caveman Cloud.

    <CodeGroup>
      ```typescript TypeScript theme={null}
      import OpenAI from "openai";

      const client = new OpenAI({
        apiKey: process.env.CAVE_API_KEY,
        baseURL: `${process.env.CAVE_GATEWAY_URL}/openai/v1`,
        defaultHeaders: {
          "x-cave-upstream-key": process.env.OPENAI_API_KEY!,
          "x-cave-agent": "support-agent",
          "x-cave-workflow": "resolve-ticket",
        },
      });

      const response = await client.chat.completions.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: "Hello, Caveman" }],
      });

      console.log(response.choices[0].message.content);
      ```

      ```python Python theme={null}
      import os
      from openai import OpenAI

      client = OpenAI(
          api_key=os.environ["CAVE_API_KEY"],
          base_url=f"{os.environ['CAVE_GATEWAY_URL']}/openai/v1",
          default_headers={
              "x-cave-upstream-key": os.environ["OPENAI_API_KEY"],
              "x-cave-agent": "support-agent",
              "x-cave-workflow": "resolve-ticket",
          },
      )

      response = client.chat.completions.create(
          model="gpt-4o",
          messages=[{"role": "user", "content": "Hello, Caveman"}],
      )

      print(response.choices[0].message.content)
      ```

      ```bash curl theme={null}
      curl "${CAVE_GATEWAY_URL}/openai/v1/chat/completions" \
        -H "authorization: Bearer ${CAVE_API_KEY}" \
        -H "x-cave-upstream-key: ${OPENAI_API_KEY}" \
        -H "x-cave-agent: support-agent" \
        -H "x-cave-workflow: resolve-ticket" \
        -H "content-type: application/json" \
        -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello, Caveman"}]}'
      ```
    </CodeGroup>

    The `x-cave-agent` and `x-cave-workflow` headers label traffic for reporting. They do not grant access.
  </Step>

  <Step title="View the trace">
    Open **Traces** in the console and look for the request you just sent. You should see the model, tokens, latency, cost, and the agent and workflow labels you attached.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Connect a Workload" icon="plug" href="/guides/connect-workload">
    Learn how to route production agent or application traffic through the Gateway.
  </Card>

  <Card title="Traces and Spend" icon="magnifying-glass" href="/guides/traces-and-spend">
    Filter, search, and understand request-level cost and latency.
  </Card>

  <Card title="Query with SQL" icon="database" href="/guides/query-with-sql">
    Run read-only SELECT over your project's requests, spans, and tool events.
  </Card>

  <Card title="Evaluations" icon="check-circle" href="/guides/evals">
    Build test cases and evaluate candidate changes against your traffic.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.