traceloop · NirBenita · Oct 29, 2025 · Oct 27, 2025 · Oct 27, 2025 · Oct 27, 2025
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,2 @@
-# Claude Code settings
 .claude/
+.package-lock.json
diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx
@@ -4,5 +4,14 @@ title: "Introduction"
 
 The following is a list of publicly available APIs you can use with the [Traceloop platform](https://app.traceloop.com).
 
-All APIs require an API key to be used. You can get one by [signing up](https://app.traceloop.com),
-and then going to the [API Keys](https://app.traceloop.com/settings/api-keys) page.
+All APIs require an API key to be used for authentication.
+
+<Note>
+  **To generate an API key:**
+  1. [Sign up](https://app.traceloop.com) for a Traceloop account if you haven't already
+  2. Go to [Settings → Organization](https://app.traceloop.com/settings/api-keys)
+  3. Select a project and environment
+  4. Click **Generate API key** and copy it immediately
+
+  [Detailed instructions →](/settings/managing-api-keys)
+</Note>
diff --git a/datasets/sdk-usage.mdx b/datasets/sdk-usage.mdx
@@ -37,9 +37,8 @@ const client = traceloop.getClient();
 </CodeGroup>
 
 <Note>
-  Make sure you've created an API key and set it as an environment variable
-  `TRACELOOP_API_KEY` before you start. Check out the SDK's [getting started
-  guide](/openllmetry/getting-started-python) for more information.
+  **Prerequisites:** You need an API key set as the environment variable `TRACELOOP_API_KEY`.
+  [Generate one in Settings →](/settings/managing-api-keys)
 </Note>
 
 The SDK fetches your datasets from Traceloop servers. Changes made to a draft dataset version are immediately available in the UI.

diff --git a/experiments/running-from-code.mdx b/experiments/running-from-code.mdx
@@ -39,9 +39,8 @@ const client = traceloop.getClient();
 </CodeGroup>
 
 <Note>
-  Make sure you've created an API key and set it as an environment variable
-  `TRACELOOP_API_KEY` before you start. Check out the SDK's [getting started
-  guide](/openllmetry/getting-started-python) for more information.
+  **Prerequisites:** You need an API key set as the environment variable `TRACELOOP_API_KEY`.
+  [Generate one in Settings →](/settings/managing-api-keys)
 </Note>
 
 

diff --git a/img/settings/project-dark.png b/img/settings/project-dark.png
diff --git a/img/settings/project-light.png b/img/settings/project-light.png
diff --git a/img/settings/projects-dark.png b/img/settings/projects-dark.png
diff --git a/img/settings/projects-light.png b/img/settings/projects-light.png
diff --git a/mint.json b/mint.json
@@ -178,6 +178,13 @@
       "group": "Prompt Management",
       "pages": ["prompts/quick-start", "prompts/registry", "prompts/sdk-usage"]
     },
+    {
+      "group": "Settings",
+      "pages": [
+        "settings/managing-api-keys",
+        "settings/projects-and-environments"
+      ]
+    },
     {
       "group": "Integrations",
       "pages": ["integrations/posthog"]

diff --git a/openllmetry/getting-started-go.mdx b/openllmetry/getting-started-go.mdx
@@ -109,21 +109,29 @@ For Traceloop, read on. For other options, see [Exporting](/openllmetry/integrat
 
 ### Using Traceloop Cloud
 
-Go to [Traceloop](https://app.traceloop.com), and create a new account.
-Then, click on **Environments** on the left-hand navigation bar. Or go to directly to https://app.traceloop.com/settings/api-keys.
-Click **Generate API Key** to generate an API key for the developement environment and click **Copy API Key** to copy it over.
+<Note>
+  You need an API key to send traces to Traceloop.
+  [Generate one in Settings](https://app.traceloop.com/settings/api-keys) by selecting
+  a project and environment, then click **Generate API key**.
 
-<Warning>Make sure to copy it as it won't be shown again.</Warning>
+  ⚠️ **Important:** Copy the key immediately - it won't be shown again after you close or reload the page.
 
-<Frame>
-  <img className="block dark:hidden" src="/img/api-key-light.png" />
-  <img className="hidden dark:block" src="/img/api-key-dark.png" />
-</Frame>
+  [Detailed instructions →](/settings/managing-api-keys)
+</Note>
+
+Set the API key as an environment variable in your app named `TRACELOOP_API_KEY`:
 
-Set the copied Traceloop's API key as an environment variable in your app named `TRACELOOP_API_KEY`.
+```bash
+export TRACELOOP_API_KEY=your_api_key_here
+```
 
 Done! You'll get instant visibility into everything that's happening with your LLM.
 If you're calling a vector DB, or any other external service or database, you'll also see it in the Traceloop dashboard.
 
+<Tip>
+  **Not seeing traces?** Make sure you're viewing the correct project and environment in the
+  dashboard that matches your API key. See [Troubleshooting](/settings/managing-api-keys#troubleshooting).
+</Tip>
+
 </Step>
 </Steps>
diff --git a/openllmetry/getting-started-nextjs.mdx b/openllmetry/getting-started-nextjs.mdx
@@ -208,21 +208,29 @@ For Traceloop, read on. For other options, see [Exporting](/openllmetry/integrat
 
 ### Using Traceloop Cloud
 
-Go to [Traceloop](https://app.traceloop.com), and create a new account.
-Then, click on **Environments** on the left-hand navigation bar. Or go to directly to https://app.traceloop.com/settings/api-keys.
-Click **Generate API Key** to generate an API key for the developement environment and click **Copy API Key** to copy it over.
+<Note>
+  You need an API key to send traces to Traceloop.
+  [Generate one in Settings](https://app.traceloop.com/settings/api-keys) by selecting
+  a project and environment, then click **Generate API key**.
 
-<Warning>Make sure to copy it as it won't be shown again.</Warning>
+  ⚠️ **Important:** Copy the key immediately - it won't be shown again after you close or reload the page.
 
-<Frame>
-  <img className="block dark:hidden" src="/img/api-key-light.png" />
-  <img className="hidden dark:block" src="/img/api-key-dark.png" />
-</Frame>
+  [Detailed instructions →](/settings/managing-api-keys)
+</Note>
 
-Set the copied Traceloop's API key as an environment variable in your app named `TRACELOOP_API_KEY`.
+Set the API key as an environment variable in your app named `TRACELOOP_API_KEY`:
+
+```bash
+export TRACELOOP_API_KEY=your_api_key_here
+```
 
 Done! You'll get instant visibility into everything that's happening with your LLM.
 If you're calling a vector DB, or any other external service or database, you'll also see it in the Traceloop dashboard.
 
+<Tip>
+  **Not seeing traces?** Make sure you're viewing the correct project and environment in the
+  dashboard that matches your API key. See [Troubleshooting](/settings/managing-api-keys#troubleshooting).
+</Tip>
+
 </Step>
 </Steps>
diff --git a/openllmetry/getting-started-python.mdx b/openllmetry/getting-started-python.mdx
@@ -86,21 +86,29 @@ For Traceloop, read on. For other options, see [Exporting](/openllmetry/integrat
 
 ### Using Traceloop Cloud
 
-Go to [Traceloop](https://app.traceloop.com), and create a new account.
-Then, click on **Environments** on the left-hand navigation bar. Or go to directly to https://app.traceloop.com/settings/api-keys.
-Click **Generate API Key** to generate an API key for the developement environment and click **Copy API Key** to copy it over.
+<Note>
+  You need an API key to send traces to Traceloop.
+  [Generate one in Settings](https://app.traceloop.com/settings/api-keys) by selecting
+  a project and environment, then click **Generate API key**.
 
-<Warning>Make sure to copy it as it won't be shown again.</Warning>
+  ⚠️ **Important:** Copy the key immediately - it won't be shown again after you close or reload the page.
 
-<Frame>
-  <img className="block dark:hidden" src="/img/api-key-light.png" />
-  <img className="hidden dark:block" src="/img/api-key-dark.png" />
-</Frame>
+  [Detailed instructions →](/settings/managing-api-keys)
+</Note>
 
-Set the copied Traceloop's API key as an environment variable in your app named `TRACELOOP_API_KEY`.
+Set the API key as an environment variable in your app named `TRACELOOP_API_KEY`:
+
+```bash
+export TRACELOOP_API_KEY=your_api_key_here
+```
 
 Done! You'll get instant visibility into everything that's happening with your LLM.
 If you're calling a vector DB, or any other external service or database, you'll also see it in the Traceloop dashboard.
 
+<Tip>
+  **Not seeing traces?** Make sure you're viewing the correct project and environment in the
+  dashboard that matches your API key. See [Troubleshooting](/settings/managing-api-keys#troubleshooting).
+</Tip>
+
 </Step>
 </Steps>
diff --git a/openllmetry/getting-started-ruby.mdx b/openllmetry/getting-started-ruby.mdx
@@ -80,21 +80,29 @@ For Traceloop, read on. For other options, see [Exporting](/openllmetry/integrat
 
 ### Using Traceloop Cloud
 
-Go to [Traceloop](https://app.traceloop.com), and create a new account.
-Then, click on **Environments** on the left-hand navigation bar. Or go to directly to https://app.traceloop.com/settings/api-keys.
-Click **Generate API Key** to generate an API key for the developement environment and click **Copy API Key** to copy it over.
+<Note>
+  You need an API key to send traces to Traceloop.
+  [Generate one in Settings](https://app.traceloop.com/settings/api-keys) by selecting
+  a project and environment, then click **Generate API key**.
 
-<Warning>Make sure to copy it as it won't be shown again.</Warning>
+  ⚠️ **Important:** Copy the key immediately - it won't be shown again after you close or reload the page.
 
-<Frame>
-  <img className="block dark:hidden" src="/img/api-key-light.png" />
-  <img className="hidden dark:block" src="/img/api-key-dark.png" />
-</Frame>
+  [Detailed instructions →](/settings/managing-api-keys)
+</Note>
 
-Set the copied Traceloop's API key as an environment variable in your app named `TRACELOOP_API_KEY`.
+Set the API key as an environment variable in your app named `TRACELOOP_API_KEY`:
+
+```bash
+export TRACELOOP_API_KEY=your_api_key_here
+```
 
 Done! You'll get instant visibility into everything that's happening with your LLM.
 If you're calling a vector DB, or any other external service or database, you'll also see it in the Traceloop dashboard.
 
+<Tip>
+  **Not seeing traces?** Make sure you're viewing the correct project and environment in the
+  dashboard that matches your API key. See [Troubleshooting](/settings/managing-api-keys#troubleshooting).
+</Tip>
+
 </Step>
 </Steps>
diff --git a/openllmetry/getting-started-ts.mdx b/openllmetry/getting-started-ts.mdx
@@ -106,21 +106,29 @@ For Traceloop, read on. For other options, see [Exporting](/openllmetry/integrat
 
 ### Using Traceloop Cloud
 
-Go to [Traceloop](https://app.traceloop.com), and create a new account.
-Then, click on **Environments** on the left-hand navigation bar. Or go to directly to https://app.traceloop.com/settings/api-keys.
-Click **Generate API Key** to generate an API key for the development environment and click **Copy API Key** to copy it over.
+<Note>
+  You need an API key to send traces to Traceloop.
+  [Generate one in Settings](https://app.traceloop.com/settings/api-keys) by selecting
+  a project and environment, then click **Generate API key**.
 
-<Warning>Make sure to copy it as it won't be shown again.</Warning>
+  ⚠️ **Important:** Copy the key immediately - it won't be shown again after you close or reload the page.
 
-<Frame>
-  <img className="block dark:hidden" src="/img/api-key-light.png" />
-  <img className="hidden dark:block" src="/img/api-key-dark.png" />
-</Frame>
+  [Detailed instructions →](/settings/managing-api-keys)
+</Note>
 
-Set the copied Traceloop's API key as an environment variable in your app named `TRACELOOP_API_KEY`.
+Set the API key as an environment variable in your app named `TRACELOOP_API_KEY`:
+
+```bash
+export TRACELOOP_API_KEY=your_api_key_here
+```
 
 Done! You'll get instant visibility into everything that's happening with your LLM.
 If you're calling a vector DB, or any other external service or database, you'll also see it in the Traceloop dashboard.
 
+<Tip>
+  **Not seeing traces?** Make sure you're viewing the correct project and environment in the
+  dashboard that matches your API key. See [Troubleshooting](/settings/managing-api-keys#troubleshooting).
+</Tip>
+
 </Step>
 </Steps>
diff --git a/openllmetry/integrations/traceloop.mdx b/openllmetry/integrations/traceloop.mdx
@@ -13,23 +13,33 @@ It allows you to deploy changes to prompts and model configurations with confide
 
 ## Connecting OpenLLMetry to Traceloop directly
 
-On Traceloop, API keys can be generated from the [Traceloop Dashboard](https://app.traceloop.com/settings/api-keys), for each of the three supported environments (Development, Staging, Production).
+<Note>
+  You need an API key to send traces to Traceloop. API keys are scoped to a specific **project** and **environment**.
 
-Go to [Traceloop Environments Management](https://app.traceloop.com/settings/api-keys)
-(you can also reach here by clicking on **Environments** on the left-hand navigation bar).
-Click on **Generate API Key**. Click **Copy Key** to copy the API key.
+  **To generate an API key:**
+  1. Go to [Settings → Organization](https://app.traceloop.com/settings/api-keys)
+  2. Click on your project (or create a new one)
+  3. Select an environment (Development, Staging, Production, or custom)
+  4. Click **Generate API key**
+  5. **Copy the key immediately** - it won't be shown again after you close or reload the page
 
-<Note>
-  API Keys are only displayed once, at the time of their creation and are not
-  stored anywhere. If you lose your API key, you will need to revoke the old one
-  and generate a new one.
+  [Detailed instructions →](/settings/managing-api-keys)
 </Note>
 
-Set the API key as an environment variable named `TRACELOOP_API_KEY`.
+Set the API key as an environment variable named `TRACELOOP_API_KEY`:
+
+```bash
+export TRACELOOP_API_KEY=your_api_key_here
+```
 
 Done! You'll get instant visibility into everything that's happening with your LLM.
 If you're calling a vector DB, or any other external service or database, you'll also see it in the Traceloop dashboard.
 
+<Tip>
+  **Want to organize your data?** Learn about [Projects and Environments](/settings/projects-and-environments)
+  to separate traces for different applications and deployment stages.
+</Tip>
+
 ## Using an OpenTelemetry Collector
 
 If you are using an [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/), you can route metrics and traces to Traceloop by simply adding an OTLP exporter to your collector configuration.

diff --git a/prompts/quick-start.mdx b/prompts/quick-start.mdx
@@ -14,9 +14,8 @@ You can use Traceloop to manage your prompts and model configurations.
 That way you can easily experiment with different prompts, and rollout changes gradually and safely.
 
 <Note>
-  Make sure you've created an API key and set it as an environment variable
-  `TRACELOOP_API_KEY` before you start. Check out the SDK's [getting started
-  guide](/openllmetry/getting-started-python) for more information.
+  **Prerequisites:** You need an API key set as the environment variable `TRACELOOP_API_KEY`.
+  [Generate one in Settings →](/settings/managing-api-keys)
 </Note>
 
 <Steps>
@@ -46,9 +45,6 @@ For more information see the [Registry Documentation](/prompts/registry).
 
 <Step title="Use the prompt in your code">
 
-If you haven't done so, make sure to [generate an API key](https://app.traceloop.com/settings/api-keys) and
-set it as an environment variable `TRACELOOP_API_KEY`.
-
 <Important>
   Make sure to initialize the SDK and enable traceloop sync (see below). On
   Typescript/Javascript, you should also wait for the initialization to