Using Nexus

Guide to using Nexus for everyday AI tasks

Last updated on: 5 de agosto de 2026

Esta página aún no está disponible en tu idioma.

Once you have completed the initial setup, you are ready to start using Nexus day to day. This guide covers the core features you will interact with regularly, from making requests to tracking costs and classifying data.

Core Features

Making Requests

Connect your applications through Nexus to access AI models.

Learn about requests →

Choosing Models

Select AI models and set up fallback chains for reliability.

Choose models →

Classifying Data

Label requests with sensitivity levels for compliance and security.

Understand classification →

Making Requests Through Nexus

Nexus acts as a gateway between your applications and AI providers like OpenAI and Anthropic. Instead of your application calling the provider directly, it routes all requests through Nexus first. This gives your organization visibility, cost tracking, security controls, and audit trails without changing how your code works.

When you make a request, Nexus receives it, checks your permissions, applies any policies (like budget limits or data classification rules), routes it to the appropriate provider, and then returns the response to your application. The entire process is transparent to your code. From your application’s perspective, it looks like it is talking directly to OpenAI or Anthropic.

How Requests Flow

Your application sends a request to Nexus using your Nexus API key (the one that starts with nxs_). Nexus authenticates the request, checks which project the key belongs to, and verifies that the request meets all policy requirements. If everything checks out, Nexus forwards the request to the AI provider using either your own provider credentials (BYOK) or the organization’s shared credentials (PTB). The provider processes the request and returns the result to Nexus, which logs the usage, calculates the cost, and sends the response back to your application.

This flow happens in milliseconds. Streaming responses work the same way—Nexus forwards each chunk as it arrives, so there is no noticeable delay.

Connecting Your Application

To connect your application to Nexus, you need two things: your Nexus gateway URL (like https://nexus.yourcompany.com) and your Nexus API key. Most applications use standard OpenAI or Anthropic SDKs and libraries. You do not need a special Nexus SDK. Just change the base URL to point to your Nexus gateway and use your Nexus API key instead of your provider key.

For technical integration steps, code examples, and SDK configuration guides, see the Nexus Developer documentation.

What Gets Tracked

Every request through Nexus is logged with metadata: which API key was used, which model was called, how many tokens were used, how much it cost, and whether the request succeeded or failed. By default, Nexus does not store the full prompt and response unless you explicitly enable tracing. This means your organization can track usage and costs without capturing sensitive data.

If you need to debug a conversation or review what was sent to the AI, you can enable tracing on a per-request basis or for an entire project. When tracing is enabled, Nexus stores the full request and response payload so you can inspect it later in the console.

Why it matters

Routing requests through Nexus adds cost tracking, security enforcement, and audit records to every AI interaction. Your organization gains visibility and control without requiring changes to your application code.

Tracking Sessions and Conversations

A session is a logical group of related requests. Think of it like a conversation: multiple back-and-forth exchanges between a user and an AI model. Without sessions, each request looks isolated. With sessions, you can see the full conversation timeline, understand how requests build on each other, and debug multi-turn interactions.

Sessions are especially useful for agentic workflows, where an AI assistant might make several requests in sequence—retrieving context, calling tools, refining answers, and synthesizing results. Grouping all these requests into one session makes it easy to trace the entire execution flow.

How to Use Sessions

To create a session, set the nexus-session-id header on your requests. The session ID can be any unique string—many teams use UUIDs, but you can use descriptive names like user-123-chat-2024-08-04 if that is easier to track. Every request with the same session ID gets grouped together.

You can also set optional session metadata to make sessions easier to identify:

nexus-session-name: A human-readable name like “Customer Support Chat” or “Data Analysis Run”
nexus-session-path: A hierarchical path like /root/child/grandchild if you want to organize sessions in a tree structure

Once you have created a session, you can view it in the Nexus console. The session timeline shows every request in chronological order, along with token usage, costs, and response times. If you enabled tracing, you can click into any request to see the full prompt and response.

Enabling Tracing

By default, Nexus logs metadata for every request (who made it, which model, tokens, cost) but does not store the full content of prompts and responses. If you want to inspect the actual conversation, you need to enable tracing.

There are several ways to enable tracing:

Per-request: Set the nexus-enable-tracing: 1 header on specific requests you want to trace
Per-API key: Configure the API key to always enable tracing
Per-project: Turn on tracing for all requests in a project
Per-organization: Enable tracing across an entire organization

Your administrator controls the default tracing settings for your organization. If tracing is disabled, you will only see metadata in the console (timestamps, token counts, costs). If tracing is enabled, you will see the full prompts, responses, and any tool calls or intermediate steps.

Tracing is stored in a tamper-evident audit system. This means once a trace is recorded, it cannot be modified or deleted. This is important for compliance and security reviews.

Viewing Sessions

In the Nexus console, navigate to the Sessions page to see a list of all your sessions. You can filter by date, session name, or project. Click on a session to open the timeline view, which shows every request in the session along with its status, latency, and cost.

If the session involves agentic workflows, you will see the full execution tree: which tools were called, what data was retrieved, how many retries occurred, and how the final response was assembled. This is especially helpful for debugging when something goes wrong.

Why it matters

Sessions group related requests so you can see the full context of a conversation or workflow. Without sessions, debugging multi-turn interactions is nearly impossible.

Choosing AI Models and Providers

Nexus connects to multiple AI providers, including OpenAI (for GPT models) and Anthropic (for Claude models). When you make a request, you specify which model you want to use. Nexus routes the request to the right provider and returns the response.

Different models have different strengths. Some are faster and cheaper but less capable. Others are more powerful but cost more. Choosing the right model for your task helps you balance quality, speed, and cost.

How to Specify Models

When you make a request, you include a model name in the request body. You can specify just the model name (like gpt-4 or claude-3-5-sonnet-20241022) or include the provider prefix (like openai/gpt-4 or anthropic/claude-3-5-sonnet-20241022).

If you do not specify a provider, Nexus automatically selects the best available option based on cost and availability. This is called automatic routing. Nexus tries to use the least expensive provider that can fulfill your request.

You can also specify a fallback chain by listing multiple models separated by commas: gpt-4,gpt-3.5-turbo. If the first model is unavailable or rate-limited, Nexus automatically tries the next model in the list. This improves reliability without requiring any changes to your application code.

BYOK vs PTB Routing

Nexus supports two billing models: Bring Your Own Key (BYOK) and Pass-Through Billing (PTB).

BYOK: You provide your own API key from OpenAI or Anthropic. The provider bills you directly. Nexus uses your key to make requests on your behalf.
PTB: Your organization provides a shared wallet with pre-purchased credits. Nexus uses its own provider credentials and deducts costs from the wallet.

When both options are available, Nexus always tries BYOK first. If your own key is unavailable or out of quota, Nexus falls back to PTB (if your organization has it enabled). This ensures requests succeed even if your personal provider account hits a limit.

Cost Optimization Strategies

Different models have very different pricing. For example:

GPT-4o is powerful but more expensive per token
GPT-4o-mini is faster and cheaper, suitable for simpler tasks
Claude 3.5 Sonnet balances cost and capability for longer conversations

To optimize costs:

Use cheaper models for routine tasks (summarization, classification, simple Q&A)
Use premium models only when you need advanced reasoning or complex outputs
Set up fallback chains to use a cheaper model if the premium model is unavailable
Monitor your usage in the console to see which models are driving costs

Nexus tracks cost per request and shows you a breakdown by model and provider in the dashboard. If costs are higher than expected, you can review your usage and switch to more cost-effective models where appropriate.

Why it matters

Choosing the right model balances quality, speed, and cost. Fallback chains improve reliability and prevent outages when a provider is unavailable.

Classifying Your Data

Data classification is how you label the sensitivity level of each request. Every request through Nexus can carry a classification tag like public, internal, confidential, or restricted. These labels help enforce security policies and ensure that sensitive data gets the right protections.

Your organization defines a classification vocabulary—a ranked list of sensitivity levels. The default vocabulary is public < internal < confidential < restricted, but your administrators can customize this to match your organization’s policies.

Why Classification Matters

Classification labels determine which security controls and policies Nexus applies to a request. The classification does not change what gets sent to the AI provider—the full request (including any sensitive data) is still forwarded to OpenAI or Anthropic. Instead, classification controls:

Access control: Whether your project is allowed to send requests at this sensitivity level. If you try to send a restricted request but your project’s classification ceiling is confidential, the request is rejected before reaching the AI provider.
Audit logging and redaction: How the request is stored in Nexus’s audit logs. For example, requests labeled confidential might have email addresses redacted when stored in the audit trail (showing ***@*** instead of customer@example.com), even though the full email was sent to the AI provider. This protects sensitive data in compliance reviews and security audits.
Provider routing: Which AI providers are approved to handle this classification level. Some organizations may restrict restricted data from being sent to certain providers, even if those providers are configured for lower classification levels.
Cost tracking and reporting: Classification labels appear in usage reports, making it easy to track spending by data sensitivity (for example, “How much did we spend on confidential requests this month?”).

Nexus enforces these policies automatically. If you send a request with a classification label that exceeds your project’s classification ceiling, the request is rejected with an error explaining which labels are allowed.

How to Set Classification

To set a classification label on a request, you include the nexus-classification header with the appropriate value when your application makes the request. This is an HTTP header, just like the Authorization header that carries your API key. Your developer adds this header to the code that calls Nexus.

For example, if you are using a tool or library that makes HTTP requests, the header might look like this in the raw HTTP request:

nexus-classification: confidential

In most programming languages and tools, you add headers when you configure the HTTP client. For instance, in Python using the OpenAI SDK, you would set custom headers like this:

from openai import OpenAI

client = OpenAI(
    base_url="https://nexus.yourcompany.com/v1",
    api_key="nxs_your_api_key_here",
    default_headers={
        "nexus-classification": "confidential"
    }
)

The classification header applies to a single request. Your developer can set a different classification for each request based on the sensitivity of the data being sent. For example, a customer support chatbot might send one request with nexus-classification: internal when a customer asks about business hours, then send the next request in the same conversation with nexus-classification: confidential when the customer provides payment information. The developer’s code detects the change in data sensitivity and adjusts the classification accordingly.

If you do not set a classification header, Nexus applies the default classification for your project. Your administrator configures this default when they set up your project. Most teams set a sensible default (like internal) so that requests are classified appropriately even if developers forget to set the header explicitly.

Who Decides the Classification?

The developer or application is responsible for knowing what data is in each request and setting the appropriate classification label. Nexus does not automatically scan the content and classify it for you. Instead, Nexus trusts the classification label provided by the developer and then enforces that the label is allowed and applies the right security controls.

This means every request going through Nexus gets a classification label—either the one explicitly set by the developer or the project’s default. All the data in that request (the prompt, the messages, any attachments) is treated as having that classification level. The developer must understand the sensitivity of the data they are sending and choose the correct label accordingly.

For example, if your team is building an HR chatbot that processes employee performance reviews (confidential data) and also answers general company policy questions (internal data), your developer needs to set nexus-classification: confidential for conversations involving performance reviews and nexus-classification: internal for policy questions. Nexus will enforce that your project is allowed to handle confidential data and will apply any required protections (like PII redaction), but it relies on the developer to label the data correctly in the first place.

Understanding Classification Tiers

Your organization’s classification vocabulary is hierarchical. Each level is more sensitive than the one before it. For example:

Public: Information that can be shared freely (marketing content, public documentation)
Internal: Information for employees only (internal memos, project plans)
Confidential: Sensitive business information (customer data, financial records)
Restricted: Highly sensitive information (trade secrets, personal health information)

Each project has a classification ceiling—the highest sensitivity level it is allowed to handle. If your project has a ceiling of confidential, you cannot send requests labeled restricted. The request will be rejected, and you will see an error message listing the allowed classification levels.

Classification and Compliance

Classification labels help your organization meet regulatory and compliance requirements by creating an auditable record of how requests were labeled and processed. When you classify requests, you create a paper trail that shows your organization has policies for identifying sensitive data, enforces limits on which projects can handle it, and logs it with appropriate protections. The classification label indicates the developer’s assessment of data sensitivity, and Nexus enforces that assessment by applying corresponding policies and access controls.

For compliance purposes, classification labels enable several critical capabilities:

Audit trail with classification context: Every request recorded in Nexus’s audit log includes its classification label along with timestamps, user identity, and request metadata. If your organization needs to demonstrate compliance with regulations like HIPAA (healthcare), GDPR (EU privacy), SOC 2 (security controls), or FedRAMP (government systems), auditors can filter the audit log by classification level to see exactly how sensitive data was processed. For example, you can generate a report showing “all confidential requests in the past year” to prove that financial data was handled according to policy.

Automated redaction for data protection: Policies can automatically redact personally identifiable information (PII) from audit logs based on classification level. For instance, requests labeled confidential or higher might have email addresses, phone numbers, or account numbers replaced with *** when stored in the audit trail. This protects sensitive data during compliance reviews and security audits while still maintaining a complete record of what happened. Note that redaction applies to how data is stored in Nexus’s logs, not to what gets sent to the AI provider.

Policy enforcement and access controls: Classification ceilings prevent projects from handling data beyond their approved sensitivity level. If a project is only approved to handle internal data, any attempt to send a confidential request will be rejected automatically. This helps organizations enforce data handling policies without relying on developers to remember the rules. Additionally, classification labels can control which AI providers are used—for example, your organization might allow public data to use any provider but restrict confidential data to specific providers that meet higher security standards.

Resource allocation and priority handling: Budget limits, rate limits, and cost tracking can be configured differently for different classification levels. This ensures that critical workloads handling sensitive data get priority access to resources. For example, your organization might set higher rate limits for confidential requests to ensure that customer-facing applications processing payment data are never throttled, while applying stricter limits to internal requests for less critical use cases.

Your administrator manages the classification vocabulary, ceilings, and policies for your organization and projects. If you need to handle data at a higher sensitivity level than your current project ceiling allows, contact your administrator to request an adjustment. They will evaluate whether your use case justifies access to more sensitive data and update the project settings accordingly.

Why it matters

Classification labels ensure sensitive data gets the right security controls and stays compliant with organizational policies. Requests without the right label are automatically rejected.

Managing Your API Keys

Your Nexus API key is how your application authenticates with the gateway. Each key is scoped to a specific project, which controls which models, providers, and resources the key can access.

API keys start with the prefix nxs_ and are project-specific. If you work on multiple projects, you may have multiple API keys—one for each project. This isolation ensures that a key from one project cannot access data or resources from another project.

When to Create New Keys

You should create a new API key when:

You are starting a new application or integration
You want to separate usage tracking between different applications
You need to grant access to a specific project without sharing other keys
You want to test changes in a development environment without affecting production

You can create as many API keys as you need for a project. Each key shows up separately in usage tracking, making it easy to see which application is driving costs.

Keeping Keys Secure

Treat your API keys like passwords. If someone gets access to your key, they can make requests on your behalf, running up costs and potentially accessing sensitive data.

Best practices for key security:

Store keys in a secure location like a password manager or secrets management system
Never share keys in emails, chat messages, or public repositories
Do not commit keys to Git or include them in code that you share publicly
Use environment variables or configuration files to load keys at runtime

If you think a key has been exposed (for example, you accidentally committed it to a public GitHub repository), revoke it immediately and create a new one. Revoked keys stop working instantly, preventing unauthorized access.

Revoking Compromised Keys

If a key is compromised, you can revoke it from the Nexus console or using the CLI:

nexus credentials api-keys revoke <key-id>

Once a key is revoked, any requests using that key will fail with a 401 Unauthorized error. Your application will need to use a new key to continue making requests.

Revoked keys are not deleted—they remain in the system for audit purposes. You can view revoked keys in the console, but they cannot be reactivated. If you need access again, create a new key.

For more details on API key rotation policies, permissions, and lifecycle management, see the Managing Teams documentation.

Why it matters

API keys are your identity in Nexus. Protecting them prevents unauthorized access and unexpected costs. Revoking compromised keys immediately stops misuse.

Understanding Rate Limits and Budgets

Nexus enforces rate limits and budget caps to prevent runaway costs and ensure fair resource allocation across your organization. Rate limits control how many requests you can make per second or per minute. Budget caps control how much you can spend per month.

These controls protect you from unexpected bills and ensure that one team or application does not monopolize resources. If you hit a rate limit or budget cap, your requests will be temporarily throttled or rejected until the limit resets.

How Rate Limits Work

Rate limits are enforced per API key. There are two types of limits:

RPS (Requests Per Second): How many requests you can make in one second
RPM (Requests Per Minute): How many requests you can make in one minute

If you exceed the limit, Nexus returns an HTTP 429 error with a Retry-After header telling you how long to wait before retrying. Most SDKs and libraries handle this automatically by backing off and retrying the request.

Your administrator sets rate limits for your project or API key. If you consistently hit rate limits, it may be a sign that you need a higher limit or that your application is making more requests than necessary.

What Happens When You Hit a Rate Limit

When you hit a rate limit, your request is rejected immediately. The response includes an error message and a Retry-After header indicating how many seconds to wait before trying again.

Your application should respect the Retry-After header and wait before retrying. If you retry too quickly, the request will be rejected again, wasting time and resources.

Most OpenAI and Anthropic SDKs handle rate limiting automatically. If your application uses these SDKs, you do not need to write custom retry logic—the SDK will back off and retry for you.

Budget Caps and Spend Tracking

Your organization may set budget caps at the workspace, organization, or project level. These caps limit how much you can spend per month on AI requests. Once you hit the cap, Nexus rejects new requests until the budget resets at the start of the next month.

Budget caps are tracked in real time. Nexus calculates the estimated cost of each request and checks it against your remaining budget before forwarding the request to the provider. If the request would exceed your budget, it is rejected with an error explaining that you have reached your spending limit.

You can view your current usage and remaining budget in the Nexus console. The dashboard shows daily, weekly, and monthly spending broken down by model and provider. If you are approaching your budget cap, you can adjust your usage or ask your administrator to increase the limit.

Managing Costs

To stay within your budget:

Monitor usage regularly in the console to see which models and applications are driving costs
Use cheaper models for routine tasks and reserve expensive models for complex work
Set up alerts (if your administrator has enabled them) to notify you when you are approaching your budget cap
Optimize prompt length to reduce token usage and costs

If your team consistently hits budget limits, talk to your administrator about increasing the cap or adjusting how costs are allocated across projects.

Why it matters

Rate limits and budget caps prevent runaway costs and ensure fair resource allocation. Monitoring usage helps you stay within budget and optimize spending.

Next Steps

Now that you understand the core features of Nexus, you may want to explore:

Managing Teams: Add team members, manage roles, and configure project settings
Reporting and Auditing: View audit logs, export usage data, and verify compliance
Nexus Developer Guide: Technical integration guides, SDK setup, and code examples

If you have questions or need help, contact your administrator or check the Frequently Asked Questions.