# OpsTower — Full Documentation > This file contains the complete OpsTower documentation concatenated into a single document for LLM consumption. > Source: https://docs.opstowerapp.com | Index: https://docs.opstowerapp.com/llms.txt --- # Agent Settings > How to configure an agent's name, AI model, connections, connected agents, and knowledge context in OpsTower. > URL: https://docs.opstowerapp.com/agents/agent-settings/ Every agent has a settings page where you control its name, AI model, data source connections, connected agents, and knowledge context. The settings page is organized into three tabs. ## General Tab The General tab contains the agent's basic configuration. - **Agent name** -- Edit the display name at any time. Choose a name that clearly describes the agent's role (e.g., "Backend Debugger" or "Growth Analyst"). - **AI model** -- By default, each agent uses the global AI model set in your account settings. You can override this on a per-agent basis by selecting a specific model from the dropdown. This is useful if you want certain agents to use a more capable model while keeping others on a lighter, faster option. - **Visibility** -- Control who can see and use this agent within your account. The visibility setting is only shown to the agent's creator. - **Everyone in this account** (default) -- All team members can see the agent in the Agents list, open its chat, and configure its settings. - **Only me** -- The agent is visible only to you. Other team members will not see it in their Agents list, cannot access it via direct URL, and cannot chat with it. Private agents still count toward your account's agent limit. Private agents also cannot be selected as connected agents by other team members. ## Settings Tab The Settings tab controls which data sources and agents are available to this agent. ### Connections Connections are displayed as a checkbox list grouped by category: - **Analytics** -- PostHog, Amplitude, GA4, Mixpanel - **Error Tracking** -- Sentry - **Payments** -- Stripe - **Logs** -- Axiom, Cloudflare, Google Cloud Logging, AWS CloudWatch - **Code** -- GitHub - **Ticketing** -- Linear - **Databases** -- Cloudflare D1, Supabase, MongoDB, SQL, DynamoDB, Firestore Only categories compatible with the agent's type are shown. A Debugger agent sees error tracking, logs, code, ticketing, and databases. An Analyst agent sees analytics, payments, and databases. Enable or disable individual connections by toggling the corresponding checkbox. Before a connection appears here, it must first be created in the [Connections](/connections/overview/) section of OpsTower. ### Connected Agents Below the connections list, you can toggle other agents as data sources for this agent. When enabled, the agent can delegate questions to the connected agent during a conversation. This is useful for cross-domain investigation -- for example, a Debugger agent asking an Analyst agent about recent metric changes while investigating an error. For more details on how this works, see [Agent-to-Agent Communication](/agents/agent-to-agent/). ## Knowledge Tab The Knowledge tab lets you attach additional context that the agent includes when answering questions. There are three types of knowledge you can configure: - **Custom knowledge** -- Free-form text that appears in the agent's system prompt. Use this for business context, architecture notes, or naming conventions. - **Knowledge files** -- PDF, TXT, or Markdown files from your shared knowledge library. Attach relevant files so the agent can reference them. - **Attached reports** -- Analytics reports that provide historical data context. For detailed information on each knowledge type and its limits, see [Knowledge](/agents/knowledge/). --- # Agent-to-Agent Communication > How to connect agents together in OpsTower so one agent can delegate questions to another agent as a data source. > URL: https://docs.opstowerapp.com/agents/agent-to-agent/ Agent-to-agent communication allows one agent to ask questions to another agent as if it were a tool or data source. This enables cross-domain investigation without requiring a single agent to have access to every data source in your stack. ## Use Case Consider a scenario where a Debugger agent is investigating a spike in API errors. While reviewing logs, it notices the errors started at a specific time. By having an Analyst agent connected, the Debugger can ask the Analyst whether any significant changes in user traffic or feature usage occurred around that same time. The Analyst queries your analytics platform and returns its findings, which the Debugger incorporates into its root cause analysis. This pattern is useful whenever an investigation benefits from data that lives outside the current agent's domain -- metrics, logs, code, or database records managed by a different agent. ## Setting Up Connected Agents 1. Navigate to the agent you want to give delegation capabilities (the "calling agent"). 2. Open the **Settings** tab on its settings page. 3. In the **Connected Agents** section, toggle on the agents you want to make available as data sources. Once enabled, the calling agent can send questions to any of its connected agents during a conversation. ## How It Works When a calling agent decides it needs information from a connected agent, it: 1. Formulates a **self-contained question** that includes all necessary context. The connected agent does not have access to the calling agent's conversation history. 2. Sends the question to the connected agent. 3. The connected agent processes the question using **its own connections and knowledge** -- querying its data sources, reasoning through the data, and generating a response. 4. The calling agent receives the response and incorporates it into its own reasoning. Because each agent operates independently with its own connections, this approach keeps data access scoped appropriately. An Analyst agent only accesses analytics data, and a Debugger agent only accesses logs and code, even when they collaborate. ## Constraints Agent-to-agent communication has the following constraints to prevent loops and maintain predictable behavior: - **No recursion.** When a connected agent processes a delegated question, it does not have access to its own connected agents. Only the top-level calling agent can delegate. - **No self-reference.** An agent cannot be connected to itself. - **No direct cycles.** If Agent A is connected to Agent B, then Agent B cannot also be connected to Agent A. - **Maximum of 10 connected agents.** Each agent can have at most 10 other agents connected to it. - **Same user only.** All connected agents must belong to the same user account. --- # Chatting with Agents > How to use the OpsTower chat interface to ask agents questions, understand how agents reason through responses, and manage conversation history. > URL: https://docs.opstowerapp.com/agents/chatting/ The chat interface is the primary way you interact with agents. You ask questions in natural language and the agent queries your connected data sources to build an answer. ## Starting a Conversation You can open a chat with an agent in two ways: - **From the agent card** -- Click on any agent in the Agents portal to open its chat. - **From the sidebar** -- If you have pinned an agent to the sidebar, click it there for quick access. ## Asking Questions Type your question in the input field and send it. The agent interprets your question, determines which connected data sources to query, and executes the necessary tool calls to gather the information it needs. You do not need to specify which data source to use. The agent decides automatically based on the question and the connections available to it. For example, asking "Why are we seeing elevated error rates on the API?" will prompt a Debugger agent to check your log provider, and potentially your code repository, without any manual direction. ## How Agents Reason Each response can involve up to **15 reasoning steps**. During these steps, the agent may: - Query one or more connected data sources - Analyze and correlate the returned data - Make follow-up queries based on initial findings - Synthesize a final answer from all gathered evidence This multi-step reasoning allows agents to handle questions that require information from several sources or that need iterative investigation. ## Web Search Agents can also search the web and fetch URL content to supplement their answers. The specific web capabilities depend on the AI provider configured for the agent: | Provider | Capabilities | | --------- | ----------------------------- | | Anthropic | Web search and URL fetching | | Google | Google Search and URL context | | OpenAI | Web search | Web search is useful when the agent needs external context -- for example, checking whether a third-party service is experiencing an outage, or looking up documentation for a library. ## Response Formatting Agent responses are rendered as markdown. This includes: - Formatted text with headings and lists - Code blocks with syntax highlighting - Tables for structured data - Inline code references ## Conversation History Message history is persisted automatically. When you return to an agent's chat, your previous conversation is still there, so you can continue where you left off or ask follow-up questions that build on earlier answers. ## Message Limits Chat messages count toward your monthly tier allocation: | Plan | Messages per Month | | -------- | ------------------ | | Free | 100 | | Pro | Unlimited | | Business | Unlimited | When you reach the Free tier limit, you will need to wait until the next billing cycle or upgrade your plan to continue chatting. --- # Creating Agents > Step-by-step instructions for creating a new Debugger or Analyst agent in OpsTower. > URL: https://docs.opstowerapp.com/agents/creating-agents/ Creating an agent in OpsTower takes just a few steps. Once created, you can configure its connections, knowledge, and model preferences from the agent settings page. ## Steps to Create an Agent 1. **Open the Agents portal.** Navigate to the Agents section from the sidebar. 2. **Click "Create Agent."** This opens the agent creation dialog. 3. **Select an agent type.** Choose between: - **Debugger** -- Investigates errors and unexpected behavior. Compatible with logs, code, and database connections. - **Analyst** -- Analyzes analytics data and trends. Compatible with analytics and database connections. Each type displays a description and the categories of connections it supports, so you can pick the right one for your use case. 4. **Give the agent a name.** Choose a descriptive name that reflects the agent's purpose. For example: - "Backend Debugger" for an agent investigating server-side errors - "Growth Analyst" for an agent tracking acquisition and conversion metrics - "Payments Debugger" for an agent focused on billing-related issues 5. **Start configuring.** After creation, you are taken to the agent's settings page where you can enable connections, attach knowledge, and adjust the AI model. See [Agent Settings](/agents/agent-settings/) for details. ## Tier Limits The number of agents you can create depends on your plan: | Plan | Max Agents | | -------- | ---------- | | Free | 2 | | Pro | 5 | | Business | Unlimited | If you reach your plan's agent limit, you will need to upgrade or remove an existing agent before creating a new one. --- # Knowledge > How to give OpsTower agents additional context through custom knowledge text, uploaded files, and attached analytics reports. > URL: https://docs.opstowerapp.com/agents/knowledge/ The knowledge system lets you provide agents with additional context beyond what they can pull from connected data sources. This context is included when the agent processes your questions, helping it give more accurate and relevant answers. There are three types of knowledge you can attach to an agent. ## Custom Knowledge Custom knowledge is free-form text that you write directly in the agent's Knowledge tab. It is injected into the agent's system prompt as additional context every time it processes a question. Use custom knowledge for: - **Business context** -- Explain what your product does, who your users are, and what metrics matter most. - **Naming conventions** -- Document how your team names services, endpoints, database tables, or analytics events so the agent can interpret data correctly. - **Architecture notes** -- Describe your infrastructure layout, service dependencies, or deployment pipeline so the agent understands how components relate. - **Known issues** -- Call out known quirks, legacy behaviors, or ongoing incidents that the agent should factor into its analysis. ### Custom Knowledge Limits | Plan | Max Size | | -------- | --------- | | Free | 10 KB | | Pro | 50 KB | | Business | Unlimited | ## Knowledge Files Knowledge files are documents you upload to a shared library and then attach to specific agents. Supported file formats are **PDF**, **TXT**, and **Markdown**. ### How File Processing Works When you upload a file, it goes through an asynchronous processing pipeline: 1. **Pending** -- The file has been uploaded and is queued for processing. 2. **Processing** -- The file content is being extracted and indexed. 3. **Ready** -- The file is fully processed and available to attach to agents. You can attach a file to an agent once its status reaches "Ready." ### Attaching Files to Agents Files live in a shared knowledge library that is accessible across all your agents. To use a file: 1. Upload it in the Knowledge section of OpsTower. 2. Navigate to the agent's **Knowledge** tab. 3. Select the files you want to attach. Each agent can have its own selection of files, so you can tailor the context each agent receives. For example, a "Backend Debugger" agent might get your infrastructure runbook, while a "Growth Analyst" agent gets your product metrics definitions document. ### Knowledge File Limits | Plan | Max Files per Agent | Max File Size | | -------- | ------------------- | ------------- | | Free | 2 | 10 MB | | Pro | 10 | 10 MB | | Business | 20 | 10 MB | ## Attached Reports You can attach analytics reports to an agent so it can reference historical data when answering questions. This is particularly useful for Analyst agents that need to compare current trends against past baselines, or for Debugger agents that need to understand whether a metric shift correlates with an incident. To attach reports: 1. Navigate to the agent's **Knowledge** tab. 2. Select from your existing reports in the attachment section. Attached reports provide the agent with the report's data and insights as context, so it can incorporate historical comparisons and trend information into its responses. ### Attached Report Limits Each agent can have a maximum of **20 attached reports**. --- # Agents Overview > Learn what agents are in OpsTower, the two agent types available, and how they connect to your data sources to answer questions and generate insights. > URL: https://docs.opstowerapp.com/agents/overview/ Agents are the core of OpsTower. They are autonomous AI workers that connect to your data sources and answer questions or generate reports on your behalf. Instead of manually querying logs, dashboards, or databases, you ask an agent a natural language question and it does the investigative work for you -- pulling data from multiple sources, correlating evidence, and delivering a clear answer. ## Agent Types OpsTower provides two specialized agent types, each designed for a distinct operational role. ### Debugger The Debugger agent investigates errors and unexpected behavior across your stack. It is built for incident response and root cause analysis. **Compatible data sources:** - **Logs** -- Axiom, Cloudflare, Google Cloud Logging, AWS CloudWatch - **Error Tracking** -- Sentry - **Code** -- GitHub repositories - **Databases** -- Cloudflare D1, Supabase, MongoDB, SQL databases, DynamoDB, Firestore - **Ticketing** -- Linear (search, view, and create issues) When you ask a Debugger agent to investigate an issue, its system prompt guides it to: 1. Gather relevant log entries, error traces, and recent code changes. 2. Correlate evidence across multiple sources to build a timeline of events. 3. Identify the most likely root cause and present its findings with supporting evidence. Debugger agents excel at questions like "Why are users getting 500 errors on the checkout endpoint?" or "What changed in the last deploy that could cause this timeout?" ### Analyst The Analyst agent analyzes analytics data and trends. It is focused on metrics exploration, trend detection, and anomaly identification. **Compatible data sources:** - **Analytics** -- PostHog, Amplitude, Google Analytics 4 (GA4), Mixpanel - **Payments** -- Stripe - **Databases** -- Cloudflare D1, Supabase, MongoDB, SQL databases, DynamoDB, Firestore Analyst agents are designed to help you understand what is happening in your product -- which features are gaining traction, where users drop off, whether a recent launch moved the needle, and what anomalies deserve attention. Analyst agents excel at questions like "How has our signup conversion rate changed over the last 30 days?" or "What are the top events by volume this week compared to last week?" ## Agent Configuration Each agent can be customized with: - **Multiple connections** -- Enable any combination of compatible data sources so the agent can pull from the sources it needs. - **Custom AI model** -- Override the global default model on a per-agent basis to use a specific provider or model. - **Knowledge context** -- Attach free-form text, uploaded files, or analytics reports to give the agent additional business context. - **Connected agents** -- Link other agents as data sources so one agent can delegate questions to another. For detailed configuration instructions, see [Agent Settings](/agents/agent-settings/). --- # Amplitude Connection > Connect Amplitude to OpsTower via OAuth to give your agents access to product analytics charts, dashboards, experiments, cohorts, and metrics. > URL: https://docs.opstowerapp.com/connections/amplitude/ The Amplitude connection integrates your Amplitude organization with OpsTower, giving agents access to product analytics data including charts, dashboards, experiments, cohorts, and metrics. Amplitude uses OAuth 2.0 for authentication, so there are no API keys to manage manually. ## Prerequisites You need an Amplitude account with permission to authorize third-party integrations. You should also know which region your Amplitude organization uses (US or EU). ## Authentication Method Amplitude uses **OAuth 2.0** for authentication. When you connect Amplitude, OpsTower opens a popup where you log in to Amplitude directly and grant access. OpsTower handles token refresh automatically, so your connection stays active without manual intervention. ## How to Connect Amplitude 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **Amplitude**. 3. Choose your **region**: - **US** -- if your Amplitude data is hosted in the United States (most common) - **EU** -- if your Amplitude data is hosted in the European Union 4. Click **Connect with Amplitude**. A popup window will open. 5. Log in to your Amplitude account if prompted. 6. Review the permissions and click **Authorize** to grant OpsTower access. 7. The popup closes automatically once authorization is complete. Your Amplitude connection will appear in the Connections list and is ready to use. ## Custom Analytics Prompt After connecting, you can optionally configure a **Custom Analytics Prompt** (max 2000 characters). This provides additional instructions for how the agent should analyze your Amplitude data. For example: - Specify which charts or dashboards are most relevant - Define key metrics and how they should be interpreted - Note any naming conventions for events or properties You can add or update this prompt at any time from the connection settings. ## What Agents Can Do with Amplitude Once connected and enabled on an agent, the agent can: - Query charts and dashboards for metrics and trends - Analyze experiment results - Explore cohort definitions and membership - Generate scheduled analytics reports with trend analysis and anomaly detection ## Usage Amplitude connections are used in two primary contexts: - **Scheduled Reports** -- automated analytics summaries delivered on a recurring schedule, covering key metrics, comparisons, and detected anomalies. - **Agent Chat via MCP** -- real-time queries during conversations with your agents, where the agent calls Amplitude through the Model Context Protocol to fetch and analyze data on demand. ## Reconnecting or Changing Accounts If you need to reconnect Amplitude -- for example, to switch to a different Amplitude organization or to fix an expired authorization: 1. Navigate to **Connections** in the sidebar. 2. Open the Amplitude connection settings. 3. Click **Reconnect**. 4. Complete the OAuth flow again in the popup. This replaces the existing authorization with a new one. ## Troubleshooting - **Popup blocked**: If the OAuth popup does not open, check your browser's popup blocker settings and allow popups from OpsTower. - **Authorization failed**: Ensure you have sufficient permissions in your Amplitude organization to authorize third-party apps. - **Wrong region**: If the connection succeeds but no data appears, verify that you selected the correct region (US or EU) matching your Amplitude organization. --- # App Store Connect Connection > Connect Apple App Store Connect to OpsTower to give your agents access to app reviews, ratings, and app metadata. > URL: https://docs.opstowerapp.com/connections/app-store-connect/ The App Store Connect connection integrates your Apple developer account with OpsTower, giving agents the ability to list your iOS and macOS apps and query customer reviews with filtering and sorting. All operations are read-only. ## Prerequisites You need an Apple Developer account enrolled in the Apple Developer Program with access to App Store Connect. The Account Holder must enable API key access if it has not been enabled before. ## Credentials Required To set up an App Store Connect connection, you need three values: - **Issuer ID** -- a UUID displayed above the key table in App Store Connect - **Key ID** -- a 10-character alphanumeric identifier shown next to each key - **Private Key (.p8)** -- an ECDSA P-256 private key file downloaded when the key is created ## How to Create an API Key 1. Sign in to [App Store Connect](https://appstoreconnect.apple.com). 2. Go to **Users and Access** > **Integrations** > **App Store Connect API**. 3. If this is your first time, the Account Holder must click **Request Access** first. 4. Select the **Team Keys** tab, then click **Generate API Key**. 5. Name it (e.g., "OpsTower Integration") and select the **Admin** role (required for analytics access). 6. Click **Generate**, then immediately **download the .p8 file**. This file can only be downloaded once. 7. Copy the **Issuer ID** (displayed above the key table) and the **Key ID** (shown in the key row). 8. Open the downloaded .p8 file in a text editor, select all the contents (including the `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` lines). ## Setup in OpsTower 1. Go to **Connections** > **App Stores** > **Add Connection**. 2. Select **App Store Connect**. 3. Paste your **Issuer ID**, **Key ID**, and the full contents of your **.p8 private key**. 4. Click **Test Connection** to verify the credentials. 5. Click **Save**. ## What Agents Can Do Once connected, agents have access to two tools: - **List Apps** -- list all apps in the account with name, bundle ID, and SKU - **Get Reviews** -- query customer reviews for a specific app, filterable by star rating (1-5) and territory (country code), sortable by date or rating, with summary statistics including average rating and rating distribution ## Use Cases - "What apps do I have in App Store Connect?" - "Show me all 1-star reviews for my app from the last week" - "What are users in the US saying about my app?" - "What's the average rating across all recent reviews?" - "Are there common complaints in the latest reviews?" - "Compare review sentiment between the US and UK markets" ## Troubleshooting - **401 Unauthorized** -- verify your Issuer ID, Key ID, and private key are correct. The .p8 file content must include the full PEM headers. - **403 Forbidden** -- ensure the API key has at least the Admin role. Some endpoints require elevated permissions. - **"Private key must be in PEM format"** -- make sure you pasted the full .p8 file contents including the `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----` lines. - **Rate limiting** -- App Store Connect allows approximately 3,600 requests per hour. Each tool call uses a single request. --- # AWS CloudWatch Logs > Connect AWS CloudWatch Logs to OpsTower for querying application logs from your AWS infrastructure. > URL: https://docs.opstowerapp.com/connections/aws-cloudwatch/ AWS CloudWatch Logs captures log data from AWS services and applications. Connecting it to OpsTower gives your agents the ability to query log groups, search for patterns, and investigate issues across your AWS infrastructure. ## What This Connection Provides Once connected, agents can: - **Query logs** -- search and filter CloudWatch log data using CloudWatch Logs Insights syntax. - **List log groups** -- discover available log groups in your AWS account and region. Agents construct CloudWatch Logs Insights queries automatically based on your natural language questions -- you do not need to write query syntax yourself. ## Credentials Needed To set up this connection, you will need: 1. **AWS Access Key ID** -- the access key for an IAM user with CloudWatch Logs read permissions. 2. **AWS Secret Access Key** -- the corresponding secret key. 3. **Region** -- the AWS region where your logs are stored. 4. **Default Log Group** (optional) -- a log group to scope all queries to. ## How to Create IAM Credentials for OpsTower 1. Go to the [AWS Console](https://console.aws.amazon.com) and navigate to **IAM** (Identity and Access Management). 2. In the left sidebar, click **Users**, then click **Create user**. 3. Enter a username (e.g., "opstower-readonly") and click **Next**. 4. On the permissions page, select **Attach policies directly**. 5. Search for and attach one of the following: - The managed policy **CloudWatchLogsReadOnlyAccess** (recommended for simplicity), or - A custom policy with the minimum required permissions: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["logs:StartQuery", "logs:GetQueryResults", "logs:DescribeLogGroups"], "Resource": "*" } ] } ``` 6. Click **Next**, review the user details, and click **Create user**. 7. Click on the newly created user to open their details. 8. Go to the **Security credentials** tab. 9. Under **Access keys**, click **Create access key**. 10. Select **Third-party service** as the use case and confirm. 11. Copy both the **Access Key ID** and the **Secret Access Key** immediately -- the secret key will not be shown again. ## Region Enter the AWS region where your CloudWatch Logs are stored. This determines which regional endpoint OpsTower queries. Common regions include: - `us-east-1` (N. Virginia) - `us-west-2` (Oregon) - `eu-west-1` (Ireland) - `eu-central-1` (Frankfurt) - `ap-southeast-1` (Singapore) If your application runs in multiple regions, create a separate connection for each region. ## Default Log Group (Optional) You can specify a default log group to scope all queries to a specific source. This is useful if you want an agent focused on a particular service. Examples: - `/aws/lambda/my-function` -- scope to a specific Lambda function. - `/aws/ecs/my-service` -- scope to an ECS service. - `/aws/apigateway/my-api` -- scope to an API Gateway. If you leave this field blank, agents can query across all log groups in the region. They will use the list log groups tool to discover available groups and target their queries accordingly. ## Setting Up the Connection 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **AWS CloudWatch Logs**. 3. Enter your **AWS Access Key ID** and **AWS Secret Access Key**. 4. Enter the **Region** where your logs are stored. 5. Optionally enter a **Default Log Group** to scope queries. 6. Save the connection. Once the connection shows a green status indicator, you can enable it on any Debugger agent to start querying your CloudWatch logs. --- # AWS DynamoDB Connection > Connect AWS DynamoDB to OpsTower to give your agents the ability to query NoSQL tables using PartiQL syntax. > URL: https://docs.opstowerapp.com/connections/aws-dynamodb/ The AWS DynamoDB connection integrates your DynamoDB tables with OpsTower, giving agents the ability to query data using PartiQL syntax. PartiQL provides a SQL-compatible query language for DynamoDB, making it straightforward for agents to look up and analyze your NoSQL data. ## Prerequisites You need an AWS account with at least one DynamoDB table in the region you want to connect. ## Credentials Required To set up a DynamoDB connection, you need three pieces of information, with one optional field: - **AWS Access Key ID** -- the access key for an IAM user with DynamoDB read permissions - **AWS Secret Access Key** -- the corresponding secret key - **Region** -- the AWS region where your DynamoDB tables are located (e.g., `us-east-1`) - **Default Table** (optional) -- scope queries to a specific table by default ## How to Create IAM Credentials 1. Log in to the [AWS Console](https://console.aws.amazon.com) and navigate to **IAM** (Identity and Access Management). 2. In the left sidebar, select **Users** and click **Create user** (or select an existing user). 3. Give the user a descriptive name (e.g., "opstower-dynamodb"). 4. On the permissions step, attach one of the following policies: **Option A -- Managed policy (recommended for simplicity)**: Attach the AWS managed policy `AmazonDynamoDBReadOnlyAccess`. This grants read access to all DynamoDB tables in the account. **Option B -- Custom policy (recommended for least privilege)**: Create an inline policy with only the permissions OpsTower needs: ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["dynamodb:ExecuteStatement", "dynamodb:ListTables", "dynamodb:DescribeTable"], "Resource": "*" } ] } ``` You can further restrict the `Resource` field to specific table ARNs if needed. 5. After creating the user, go to **Security credentials** and click **Create access key**. 6. Select **Third-party service** as the use case. 7. Copy both the **Access Key ID** and **Secret Access Key** immediately -- the secret key will not be shown again. Store these credentials securely. If you lose the secret key, you will need to create a new access key pair. ## How to Find Your Region Your DynamoDB tables are region-specific. To find the correct region: 1. In the AWS Console, navigate to **DynamoDB**. 2. Check the region selector in the top-right corner of the console. The current region code (e.g., `us-east-1`, `eu-west-1`) is displayed there. 3. Ensure you can see your tables listed. If not, switch to the correct region. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **AWS DynamoDB**. 3. Enter your **AWS Access Key ID**, **AWS Secret Access Key**, and **Region**. 4. Optionally, set a **Default Table** to scope queries to a specific table. 5. Click **Save** to create the connection. ## What Agents Can Do with DynamoDB Once connected and enabled on an agent, the agent can: - Query tables using PartiQL syntax (a SQL-compatible language for DynamoDB) - List all DynamoDB tables in the configured region - Describe table structures, including key schemas and indexes ## PartiQL Query Notes PartiQL lets you query DynamoDB with SQL-like syntax. A few important things to know: - **Include the partition key in queries** for best performance. Queries without a partition key result in a full table scan, which is slower and more expensive. - **Example query**: `SELECT * FROM "Users" WHERE "userId" = 'abc123'` - **Table and attribute names** with special characters or uppercase letters should be enclosed in double quotes. - PartiQL through OpsTower is read-only. Write operations (INSERT, UPDATE, DELETE) are not supported. ## Troubleshooting - **Authentication errors**: Verify that your Access Key ID and Secret Access Key are correct and that the IAM user has not been deactivated. - **Access denied**: Ensure the IAM user has the required permissions (`dynamodb:ExecuteStatement`, `dynamodb:ListTables`, `dynamodb:DescribeTable`). Check for any restrictive IAM policies or service control policies. - **No tables found**: Confirm that the region is correct. DynamoDB tables are region-specific, so tables in `us-east-1` will not appear when querying `eu-west-1`. - **Slow queries**: Include the partition key in your PartiQL queries to avoid full table scans. If querying by non-key attributes, consider whether a Global Secondary Index (GSI) exists for those attributes. --- # Axiom > Connect Axiom to OpsTower for structured log querying using APL (Axiom Processing Language). > URL: https://docs.opstowerapp.com/connections/axiom/ Axiom is a log management and observability platform. Connecting it to OpsTower gives your agents the ability to query structured logs using APL (Axiom Processing Language), returning up to 100 results per query. ## What This Connection Provides Once connected, agents can: - Query structured log data from your Axiom datasets using APL syntax. - Filter, aggregate, and search log entries to investigate issues or answer operational questions. Agents construct APL queries automatically based on your natural language questions -- you do not need to write APL yourself. Each query returns a maximum of 100 results. ## Credentials Needed To set up this connection, you will need: 1. **API Token** -- an Axiom API token with read access to your datasets. 2. **Dataset Name** -- the name of the Axiom dataset you want to query. ## How to Get Your Axiom API Token 1. Log in to Axiom at [app.axiom.co](https://app.axiom.co). 2. Click your profile icon in the bottom-left corner and go to **Settings**. 3. Navigate to **API Tokens** in the settings menu. 4. Click **New API Token**. 5. Give the token a descriptive name (e.g., "OpsTower Read Access"). 6. Select the datasets that this token should have access to. For security, grant access only to the datasets you plan to query from OpsTower. 7. Click **Create** and copy the token immediately -- it will not be shown again. Your API token will start with `xaat-` (personal token) or `xapt-` (advanced API token). ## How to Find Your Dataset Name 1. In Axiom, click **Datasets** in the left sidebar. 2. Your datasets are listed with their names displayed as identifiers. Dataset names are alphanumeric and may include hyphens or underscores (e.g., `my-app-logs`, `production_events`). 3. Copy the exact dataset name and enter it when configuring the connection in OpsTower. ## Setting Up the Connection 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **Axiom**. 3. Enter your **API Token** and **Dataset Name**. 4. Save the connection. Once the connection shows a green status indicator, you can enable it on any Debugger agent to start querying your logs. --- # Bitbucket Cloud Connection > Connect Bitbucket Cloud to OpsTower to give your agents access to repositories, source code, commits, pull requests, and CI/CD pipeline status. > URL: https://docs.opstowerapp.com/connections/bitbucket/ The Bitbucket Cloud connection integrates your Bitbucket workspace with OpsTower, giving agents the ability to browse repositories, read source files, search code, inspect commits and diffs, review pull requests, and monitor pipeline (CI/CD) status. This mirrors the GitHub integration with Bitbucket-specific features like PR tracking and pipeline monitoring. ## Prerequisites You need a Bitbucket Cloud account. The connection uses OAuth 2.0, so you authorize OpsTower to access your workspace directly from the UI. Code search requires a Bitbucket Standard or Premium plan. ## Setup in OpsTower 1. Go to **Connections** > **Code** > **Add Connection**. 2. Select **Bitbucket**. 3. Click **Connect to Bitbucket**. 4. A popup opens to Bitbucket's authorization page. Sign in and grant access. 5. OpsTower automatically discovers your workspace and stores the connection. 6. Optionally configure: - **Default Branch** -- the default branch for browsing and commits (default: `main`) - **Restrict to Repository** -- limit agents to a single repo (format: `workspace/repo-slug`) ## What Agents Can Do Once connected, agents have access to eight tools: - **List Repositories** -- discover all repos in the connected workspace with language, visibility, and default branch - **Browse Repository** -- explore directory structure at any path and branch - **Read File** -- read file contents with line numbers, line range filtering, and binary detection (100KB limit) - **Search Code** -- search for code patterns across the workspace or a specific repo (requires Standard/Premium plan) - **List Commits** -- view recent commits with author, date, and message, filtered by branch or path - **Get Commit** -- inspect a specific commit's details with parallel diffstat showing changed files and line counts - **List Pull Requests** -- browse PRs by state (OPEN, MERGED, DECLINED, SUPERSEDED) with author, reviewers, and comment counts - **List Pipelines** -- monitor CI/CD pipeline runs with status, branch, duration, and trigger info ## Use Cases - "Show me the most recent commits to the payments service" - "Find all usages of the `chargeCustomer` function across our workspace" - "What pull requests are currently open and waiting for review?" - "Read the `src/services/billing.ts` file in our API repo" - "What pipeline runs failed on the main branch today?" - "What changed in commit abc1234?" ## Troubleshooting - **OAuth popup blocked** -- allow popups for the OpsTower domain and try again - **Code search returns 403** -- code search requires a Bitbucket Standard or Premium workspace plan - **Pipelines not found (404)** -- pipelines are not enabled for the repository, or the pipeline OAuth scope was not granted during connection - **Token expired** -- click "Reconnect to Bitbucket" to refresh the OAuth tokens - **Cross-workspace access** -- Bitbucket scopes API access to the connected user's workspace; agents can access any repo the user has permission to within that workspace --- # Braintree Connection > Connect Braintree to OpsTower to give your agents access to transaction data, subscription analytics, dispute tracking, and customer vault searches. > URL: https://docs.opstowerapp.com/connections/braintree/ The Braintree connection integrates your Braintree payment gateway with OpsTower, giving agents the ability to search transactions for revenue analysis, query subscriptions with MRR calculations, monitor disputes and chargebacks, and search the customer vault. All operations are read-only. ## Prerequisites You need a Braintree account (PayPal-owned) with API access. Both production and sandbox environments are supported. ## Credentials Required To set up a Braintree connection, you need: - **Merchant ID** -- your Braintree merchant identifier - **Public Key** -- API public key for authentication - **Private Key** -- API private key for authentication - **Environment** -- production or sandbox ## How to Find Your Braintree API Keys 1. Log in to your **Braintree Control Panel** (production: `braintreegateway.com`, sandbox: `sandbox.braintreegateway.com`). 2. Go to **Settings** > **API**. 3. Find your **Merchant ID** at the top of the page. 4. Under **API Keys**, click **Generate New API Key**. 5. Copy the **Public Key** and **Private Key**. ## Setup in OpsTower 1. Go to **Connections** > **Payments** > **Add Connection**. 2. Select **Braintree**. 3. Choose your **Environment** (production or sandbox). 4. Enter your **Merchant ID**, **Public Key**, and **Private Key**. 5. Click **Test Connection** to verify the credentials. 6. Click **Save**. ## What Agents Can Do Once connected, agents have access to four tools: - **Query Transactions** (GraphQL API) -- search settled transactions for revenue analysis, filter by status, date range, and amount. Supports statuses: SETTLED, SUBMITTED_FOR_SETTLEMENT, AUTHORIZED, VOIDED, FAILED, PROCESSOR_DECLINED, GATEWAY_REJECTED - **Query Subscriptions** (REST API) -- list subscriptions by status (Active, Canceled, PastDue, Pending, Expired) with MRR calculation from active subscriptions - **Query Disputes** (GraphQL API) -- search disputes and chargebacks by status (OPEN, WON, LOST, ACCEPTED, EXPIRED) with reply deadlines and linked transaction details - **Query Customers** (REST API) -- search the customer vault by email, name, or date range with payment methods on file **Important:** All monetary amounts from Braintree are in full currency units (dollars), not cents. A value of `10.00` means $10.00. ## Use Cases - "How much revenue did we process in Braintree last month?" - "Show me all settled transactions above $500 this week" - "What disputes are currently open and when do we need to respond?" - "How many active subscriptions do we have and what's the MRR?" - "Find customer john@example.com in the Braintree vault" ## Troubleshooting - **Authentication errors** -- Braintree GraphQL always returns HTTP 200; authentication errors appear in the response body. Verify all three credentials (Merchant ID, Public Key, Private Key) are correct - **Subscriptions not found** -- subscription search uses the Braintree REST API (not GraphQL) since GraphQL subscription search is not yet available - **Sandbox vs production** -- make sure your credentials match the selected environment --- # Chargebee Connection > Connect Chargebee to OpsTower to give your agents access to subscription data, invoices, customers, transactions, and pricing catalogs. > URL: https://docs.opstowerapp.com/connections/chargebee/ The Chargebee connection integrates your Chargebee account with OpsTower, giving agents the ability to query subscriptions with MRR calculations, analyze invoices, search customers, review payment transactions, and inspect your pricing catalog. All operations are read-only. ## Prerequisites You need a Chargebee account with API access. Both live and test sites are supported. Chargebee uses site-specific subdomains -- your live site is `mycompany.chargebee.com` and test site is typically `mycompany-test.chargebee.com`. ## Credentials Required To set up a Chargebee connection, you need: - **Site Subdomain** -- your Chargebee site name (e.g., `mycompany`, not the full URL) - **API Key** -- a Chargebee read-only API key ## How to Create a Chargebee API Key 1. In your Chargebee Dashboard, go to **Settings** > **API Keys & Webhooks** > **API Keys**. 2. Click **Generate Key**. 3. Set Type to **Read-Only: Restricted**. 4. Check both **Transactional Data** and **Product Catalog** sub-scopes. 5. Name it something like "OpsTower Read Only". 6. Copy the key and paste it into OpsTower. For test mode, use your test site subdomain (typically `mycompany-test`). ## Setup in OpsTower 1. Go to **Connections** > **Payments** > **Add Connection**. 2. Select **Chargebee**. 3. Enter your **Site Subdomain** and **API Key**. 4. Click **Test Connection** to verify the credentials. 5. Click **Save**. ## What Agents Can Do Once connected, agents have access to five tools: - **Query Subscriptions** -- list subscriptions by status (active, cancelled, in_trial, non_renewing, paused, future) with MRR calculation using Chargebee's native MRR field - **Query Invoices** -- search invoices by status (paid, posted, payment_due, not_paid, voided, pending) and date range - **Query Customers** -- search customers by email or company name with balance information - **Query Transactions** -- search payment transactions and refunds with payment method and gateway details - **Query Item Prices** -- browse the pricing catalog (plans, addons, charges) with billing cycles and pricing models. Automatically falls back to the legacy Plan model for older Chargebee sites. ## Use Cases - "What's our current MRR from active Chargebee subscriptions?" - "Show me all failed transactions this week" - "How many customers are currently in trial?" - "What invoices are overdue right now?" - "List our pricing plans and their billing cycles" ## Troubleshooting - **401 Unauthorized** -- verify your API key is correct and has not been revoked - **404 on item prices** -- your site may use the legacy Plan model; the tool automatically falls back to the `/plans` endpoint - **Rate limiting** -- Chargebee allows 150-750 requests per minute depending on your plan; each tool call uses a single request --- # ClickHouse Connection > Connect your ClickHouse database to OpsTower to give your agents read-only SQL query access for analytics data lookups and analysis. > URL: https://docs.opstowerapp.com/connections/clickhouse/ The ClickHouse connection integrates your ClickHouse database with OpsTower, giving agents the ability to run read-only SQL queries against your columnar analytics data. All queries are executed in read-only mode, return results in JSON format, and are capped at 100 rows per query. ## Prerequisites You need a ClickHouse instance that is accessible over HTTP or HTTPS. Both ClickHouse Cloud and self-hosted instances are supported. ## Credentials Required To set up a ClickHouse connection, you need the following: - **URL** -- the HTTP(S) endpoint of your ClickHouse instance - **Username** -- a ClickHouse user with read access (defaults to `default`) - **Password** -- the password for the ClickHouse user - **Database** (optional) -- the default database for queries (defaults to `default`) ## How to Find Your Credentials (ClickHouse Cloud) If you are using ClickHouse Cloud: 1. Log in to [clickhouse.cloud](https://clickhouse.cloud) and open your service. 2. Click **Connect** in the top-right corner of the service overview. 3. The connection dialog displays your **hostname** (the URL), **port** (`8443`), and **username** (`default`). 4. If you do not have your password, click **Reset password** to generate a new one. For self-hosted instances, use the HTTP(S) endpoint and credentials configured by your administrator. ## Connection URL Formats ### ClickHouse Cloud ``` https://..clickhouse.cloud:8443 ``` You can find this URL in the **Connect** dialog of your ClickHouse Cloud service. ### Self-Hosted (HTTPS) ``` https://your-host:8443 ``` ### Self-Hosted (HTTP) ``` http://your-host:8123 ``` The URL must be accessible from the internet. If your ClickHouse instance is behind a private network, you will need to configure network access before connecting. ## Security Considerations OpsTower enforces read-only mode at the ClickHouse client level (`readonly=1` session setting). All queries are validated before execution to reject write operations. However, it is strongly recommended to create a dedicated read-only user for OpsTower. ### Creating a Read-Only User ```sql CREATE USER opstower IDENTIFIED BY 'your-secure-password' SETTINGS readonly = 1; GRANT SELECT ON your_database.* TO opstower; ``` This ensures that even if OpsTower's query validation were bypassed, the database user itself cannot perform mutations. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **ClickHouse**. 3. Enter your **URL**, **Username**, and **Password**. 4. Optionally specify a **Database** name (leave blank to use the `default` database). 5. Click **Test Connection** to verify your credentials. 6. Click **Save** to create the connection. ## What Agents Can Do with ClickHouse Once connected and enabled on an agent, the agent can: - Execute read-only SQL queries against your ClickHouse database - List all tables and their column schemas using system table introspection - Use ClickHouse-specific SQL features including `toStartOfHour()`, `uniq()`, `LIMIT N BY`, and other columnar query patterns ClickHouse is a columnar database optimized for analytics workloads. Agents are guided to write efficient queries that take advantage of ClickHouse's strengths -- for example, selecting only needed columns rather than using `SELECT *`, and leveraging time-bucketing functions for time-series analysis. ## Troubleshooting - **Connection refused**: Verify that the URL and port are correct. ClickHouse Cloud uses port `8443` (HTTPS). Self-hosted instances typically use `8443` (HTTPS) or `8123` (HTTP). - **Authentication failed**: Double-check the username and password. Ensure the user exists and has the correct permissions on the target database. - **Database not found**: If you specified a database name, verify that it exists on the ClickHouse instance. You can leave the database field blank to use the `default` database. - **Timeout errors**: Ensure your ClickHouse instance is reachable from the internet. For ClickHouse Cloud, check that your service is running and not paused. - **Permission denied on tables**: Verify that the ClickHouse user has SELECT privileges on the tables you want to query. Use `SHOW GRANTS FOR your_user` to check. --- # Cloudflare D1 Connection > Connect Cloudflare D1 to OpsTower to give your agents read-only SQL query access to your serverless SQLite databases. > URL: https://docs.opstowerapp.com/connections/cloudflare-d1/ The Cloudflare D1 connection integrates your D1 databases with OpsTower, giving agents the ability to run read-only SQL queries against your serverless SQLite databases. All queries are limited to SELECT statements and return a maximum of 100 rows per query. ## Prerequisites You need a Cloudflare account with at least one D1 database created under Workers & Pages. ## Credentials Required To set up a Cloudflare D1 connection, you need three pieces of information: - **API Token** -- a Cloudflare API token with D1 read permissions - **Account ID** -- your Cloudflare account identifier - **Database ID** -- the UUID of the specific D1 database to query ## How to Create an API Token 1. Log in to the Cloudflare dashboard at [dash.cloudflare.com](https://dash.cloudflare.com). 2. Click your profile icon in the top-right corner and go to **My Profile**. 3. Select **API Tokens** from the left sidebar. 4. Click **Create Token**. 5. Choose **Create Custom Token**. 6. Give the token a descriptive name (e.g., "OpsTower D1 Read"). 7. Under **Permissions**, add: - **Account** -- **D1** -- **Read** 8. Under **Account Resources**, select the account that contains your D1 database. 9. Click **Continue to summary**, then **Create Token**. 10. Copy the token immediately -- it will not be shown again. Store this token securely. If you lose it, you will need to create a new one. ## How to Find Your Account ID 1. Log in to the Cloudflare dashboard at [dash.cloudflare.com](https://dash.cloudflare.com). 2. Select your account. 3. The **Account ID** is displayed in the right sidebar on the account overview page. It is a 32-character hexadecimal string. You can also find the Account ID in the URL when viewing your account: `https://dash.cloudflare.com//...` ## How to Find Your Database ID 1. In the Cloudflare dashboard, navigate to **Workers & Pages** in the sidebar. 2. Select **D1** from the submenu. 3. Click the name of the database you want to connect. 4. On the database overview page, the **Database ID** is displayed near the top. It is a UUID (e.g., `a1b2c3d4-e5f6-7890-abcd-ef1234567890`). ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **Cloudflare D1**. 3. Enter your **API Token**, **Account ID**, and **Database ID**. 4. Click **Save** to create the connection. ## What Agents Can Do with Cloudflare D1 Once connected and enabled on an agent, the agent can: - Execute read-only SQL queries (SELECT statements only) against your D1 database - List all tables in the database - Inspect table schemas to understand your data structure All queries are validated as read-only before execution. Write operations (INSERT, UPDATE, DELETE, DROP, etc.) are rejected. ## Troubleshooting - **Authentication errors**: Verify that your API token is correct and has the "Account > D1 > Read" permission. Generate a new token if needed. - **No data returned**: Confirm that the Database ID matches the correct database and that the database contains data. - **Permission denied**: Ensure the API token's account resources include the account where the D1 database resides. - **Query errors**: D1 uses SQLite syntax. If your query fails, check that you are using SQLite-compatible SQL. --- # Cloudflare Workers Logging > Connect Cloudflare Workers telemetry to OpsTower for querying request logs, console output, and errors from your Workers. > URL: https://docs.opstowerapp.com/connections/cloudflare-logging/ Cloudflare Workers Logging gives your agents access to Workers telemetry data -- request logs, console output, and errors generated by your Cloudflare Workers. This is useful for debugging Worker behavior, tracing request flows, and identifying error patterns. ## What This Connection Provides Once connected, agents can: - **Query logs** -- search and filter Workers telemetry data including HTTP request logs, `console.log` output, and uncaught exceptions. - **List available log keys** -- discover which fields are available in your Workers telemetry data. - **List values for specific keys** -- explore the distinct values for any log field to understand your data. The default lookback period is 24 hours, with a maximum of 7 days. ## Credentials Needed To set up this connection, you will need: 1. **API Token** -- a Cloudflare API token with Workers read permissions. 2. **Account ID** -- your Cloudflare account identifier. 3. **Script Name** (optional) -- the name of a specific Worker to scope logs to. ## How to Get Your Cloudflare API Token 1. Go to [dash.cloudflare.com](https://dash.cloudflare.com). 2. Click your profile icon in the top-right corner and select **My Profile**. 3. Go to the **API Tokens** tab. 4. Click **Create Token**. 5. You can either: - Use the **Read All Resources** template for broad read access, or - Click **Create Custom Token** and grant the following permissions: - **Account > Workers Scripts > Read** - **Account > Workers Tail > Read** 6. Complete the token creation flow and copy the token immediately -- it will not be shown again. ## How to Find Your Account ID 1. Log in to the Cloudflare dashboard at [dash.cloudflare.com](https://dash.cloudflare.com). 2. Select any domain, or navigate to **Workers & Pages** in the sidebar. 3. Your **Account ID** is displayed in the right sidebar under **Account details**. 4. It is a 32-character hexadecimal string (e.g., `a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6`). ## Script Name (Optional) If you want to scope log queries to a specific Worker, enter the Worker's script name. This is the name shown in your Workers & Pages dashboard. If you leave this field blank, agents will query logs across all Workers in your account. ## Setting Up the Connection 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **Cloudflare Workers Logging**. 3. Enter your **API Token** and **Account ID**. 4. Optionally enter a **Script Name** to limit queries to a specific Worker. 5. Save the connection. Once the connection shows a green status indicator, you can enable it on any Debugger agent to start querying your Workers telemetry. --- # External API Connection > Connect any REST API to OpsTower so your agents can query external services with automatic authentication and SSRF protection. > URL: https://docs.opstowerapp.com/connections/external-api/ The External API connection lets you integrate any REST API with OpsTower. Instead of waiting for a dedicated integration, you can point an agent at any HTTP endpoint -- an internal microservice, a third-party SaaS API, a partner data feed -- and give it the credentials to authenticate automatically. ## When to Use This Use the External API connection when: - You rely on a service OpsTower does not have a dedicated integration for yet - You have internal APIs or microservices your agents should be able to query - You want to pull data from a third-party REST API that uses standard authentication ## Authentication Methods The External API connection supports five authentication methods: | Method | How It Works | | ----------------- | ---------------------------------------------------------------------- | | **Bearer Token** | Sends an `Authorization: Bearer ` header on every request | | **API Key Header**| Sends a custom header (e.g., `X-API-Key: `) on every request | | **Basic Auth** | Sends an `Authorization: Basic ` header on every request | | **Query Parameter**| Appends a key-value pair to the URL query string on every request | | **No Auth** | No credentials attached -- for open or internally-networked endpoints | All credentials are encrypted at rest using AES-GCM. Agents never see raw secrets -- authentication is injected automatically before each request. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **External API**. 3. Enter a **Label** (optional) -- a friendly name like "Internal Billing API" or "Weather Service." 4. Enter the **Base URL** -- the root URL of the API (e.g., `https://api.example.com/v1`). All agent requests will be relative to this URL. 5. Choose the **Authentication Type** and fill in the required credentials. 6. Optionally provide: - **API Documentation URL** -- a link to the API docs or OpenAPI spec. Agents can fetch this at runtime to learn the available endpoints. - **API Description** -- free-text context about what the API does and which endpoints are useful. This is injected into the agent's context so it knows how to use the API. 7. Click **Test Connection** to verify the base URL is reachable with the provided credentials. 8. Click **Save** to create the connection. ## What Agents Can Do Once connected and enabled on an agent, the agent can make HTTP requests to the API: - **GET, POST, PUT, PATCH, DELETE** -- all standard HTTP methods are supported - **Path construction** -- the agent appends a path to your base URL (e.g., `/users`, `/orders/123`) - **Query parameters** -- the agent can add query string parameters - **Request bodies** -- the agent can send JSON or other content types for POST/PUT/PATCH - **Custom headers** -- the agent can add headers (security-sensitive headers like `Authorization` and `Cookie` are blocked to prevent overriding configured credentials) Responses are returned as text and capped at 8KB to keep agent context manageable. A 15-second timeout is enforced on all requests. ## Providing API Context The more context you give, the better your agents will use the API. There are two optional fields that significantly improve agent performance: ### API Documentation URL If the API has documentation or an OpenAPI/Swagger spec available at a URL, provide it. Agents with web tools enabled can fetch the docs at runtime to discover endpoints, required parameters, and response schemas. ### API Description Write a plain-text description of the API. Include: - What the API does and what data it provides - Key endpoints the agent should know about (e.g., `GET /users` returns a list of users) - Important notes about pagination, rate limits, or response formats - Any domain-specific terminology the agent should understand This text is injected directly into the agent's tool description, so keep it concise and actionable. ## Security The External API connection includes several safety measures: - **SSRF protection** -- all constructed URLs are validated to stay on the same origin as the configured base URL, preventing path-based redirect attacks - **Header sanitization** -- agents cannot override authentication headers (`Authorization`, `Cookie`) or inject dangerous headers (`Host`, `Transfer-Encoding`) - **Credential encryption** -- all secrets are encrypted at rest with AES-GCM - **Request timeout** -- a 15-second timeout prevents hanging connections - **Response cap** -- responses are truncated at 8KB to avoid context overflow ## Use Cases - **Internal tools**: Connect your admin API so agents can look up user accounts, check feature flags, or pull internal metrics - **Partner APIs**: Let agents query a partner data feed for pricing, inventory, or status checks - **SaaS platforms**: Connect any SaaS tool with a REST API -- CRM, helpdesk, shipping provider, etc. - **Webhook receivers**: Point agents at status endpoints for CI/CD, deployment pipelines, or health checks ## Agent Type Compatibility The External API connection is available to all agent types: Analyst, Debugger, Product Manager, and Custom. ## Troubleshooting - **Connection test fails**: Verify the base URL is correct and reachable. Check that the authentication credentials are valid. The test sends a basic request to the base URL. - **Agent gets 401/403 errors**: The credentials may have expired or lack the required permissions. Update the connection with fresh credentials. - **Responses are truncated**: The 8KB response cap keeps agent context manageable. If the API returns large payloads, guide the agent (via the API description field) to use query parameters or endpoints that return smaller result sets. - **Requests time out**: The API must respond within 15 seconds. If the endpoint is slow, consider pointing agents at a faster or cached version. --- # Google Analytics 4 Connection > Connect Google Analytics 4 to OpsTower using a GCP service account to give your agents access to web and app analytics data. > URL: https://docs.opstowerapp.com/connections/ga4/ The Google Analytics 4 (GA4) connection integrates your GA4 property with OpsTower, giving agents access to web and app analytics data from Google's measurement platform. This connection uses a GCP service account for authentication, which requires a JSON key file and your GA4 Property ID. ## Prerequisites - A Google Cloud Platform (GCP) project (existing or new) - A Google Analytics 4 property with data - Permission to create service accounts in GCP and manage access in GA4 ## Credentials Required To set up a GA4 connection, you need two things: - **Service Account JSON Key** -- a credentials file from a GCP service account - **Property ID** -- the numeric identifier for your GA4 property ## How to Create a GCP Service Account 1. Go to [Google Cloud Console](https://console.cloud.google.com). 2. Select an existing project or create a new one. 3. In the left sidebar, navigate to **IAM & Admin** > **Service Accounts**. 4. Click **Create Service Account**. 5. Enter a name for the service account (e.g., "opstower-analytics"). 6. Optionally add a description (e.g., "Read-only access for OpsTower analytics"). 7. Click **Create and Continue**. 8. Grant the role **Viewer** on the project. This provides sufficient read access for analytics queries. 9. Click **Continue**, then click **Done**. 10. In the service accounts list, click the service account you just created. 11. Go to the **Keys** tab. 12. Click **Add Key** > **Create new key**. 13. Select **JSON** as the key type and click **Create**. 14. The JSON file will download automatically. Keep this file secure -- you will paste its contents into OpsTower. ## How to Grant GA4 Access to the Service Account The service account needs read access to your GA4 property. You grant this through the Google Analytics admin panel. 1. Open [Google Analytics](https://analytics.google.com). 2. Go to **Admin** (gear icon in the bottom-left corner). 3. In the Property column, click **Property Access Management**. 4. Click the **+** button to add a new user. 5. Enter the service account's email address. You can find this in the JSON file under the `client_email` field (it looks like `name@project-id.iam.gserviceaccount.com`). 6. Set the role to **Viewer**. 7. Click **Add**. The service account can now read data from this GA4 property. ## How to Find Your Property ID 1. In [Google Analytics](https://analytics.google.com), go to **Admin**. 2. In the Property column, click **Property Settings**. 3. The **Property ID** is a numeric value displayed at the top of the settings page (e.g., `123456789`). 4. When entering the Property ID in OpsTower, you can use either the plain number (`123456789`) or the full format (`properties/123456789`). ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **GA4**. 3. Paste the full contents of your **Service Account JSON** file into the credentials field. 4. Enter your **Property ID**. 5. Optionally, add a **Custom Analytics Prompt** with instructions for how the agent should analyze your GA4 data (max 2000 characters). 6. Click **Save** to create the connection. ## What Agents Can Do with GA4 Once connected and enabled on an agent, the agent can: - Query page views, sessions, and user metrics over time ranges - Analyze traffic sources and acquisition channels - Review event data and conversions - Generate scheduled analytics reports with trend analysis and anomaly detection ## Usage GA4 connections are used in two primary contexts: - **Scheduled Reports** -- automated analytics summaries delivered on a recurring schedule, covering key metrics, period-over-period comparisons, and detected anomalies. - **Agent Chat via MCP** -- real-time queries during conversations with your agents, where the agent calls GA4 through the Model Context Protocol to fetch and analyze data on demand. ## Troubleshooting - **Permission denied errors**: Verify that the service account email has been added to the GA4 property with Viewer access. Also confirm that the JSON key file has not been revoked in GCP. - **No data returned**: Double-check that the Property ID is correct and that the property has recent data. Ensure you are using a GA4 property, not a Universal Analytics property. - **Invalid JSON key**: Make sure you pasted the entire contents of the JSON file, including the opening and closing braces. Do not modify the file contents. - **Wrong project**: If you have multiple GCP projects, ensure the service account belongs to a project where the necessary APIs are enabled. The Google Analytics Data API should be enabled in the GCP project. --- # Google Cloud Firestore Connection > Connect Google Cloud Firestore to OpsTower to give your agents document query access with filtering and aggregation support. > URL: https://docs.opstowerapp.com/connections/gcloud-firestore/ The Google Cloud Firestore connection integrates your Firestore databases with OpsTower, giving agents the ability to query documents, retrieve specific documents by path, and list collections. The connection supports filtering, ordering, and aggregation operations. ## Prerequisites You need a Google Cloud project with Firestore enabled (either Native mode or Datastore mode). ## Credentials Required To set up a Firestore connection, you need the following: - **Service Account JSON** -- a JSON key file for a GCP service account with Firestore read access - **GCP Project ID** -- the identifier for your Google Cloud project - **Database ID** (optional) -- the Firestore database ID, defaults to `(default)` ## How to Create a Service Account 1. Go to the [Google Cloud Console](https://console.cloud.google.com). 2. Select your project from the project picker at the top of the page. 3. Navigate to **IAM & Admin** > **Service Accounts** in the left sidebar. 4. Click **Create Service Account**. 5. Enter a name for the service account (e.g., "opstower-firestore") and an optional description. 6. Click **Create and Continue**. 7. On the **Grant this service account access to project** step, add the role **Cloud Datastore Viewer** (`roles/datastore.viewer`). This grants read-only access to Firestore data. 8. Click **Continue**, then **Done**. 9. Find your newly created service account in the list and click on it. 10. Go to the **Keys** tab. 11. Click **Add Key** > **Create new key**. 12. Select **JSON** as the key type and click **Create**. 13. The JSON key file will download automatically. Store it securely. The JSON key file contains sensitive credentials. Do not commit it to version control or share it publicly. ## How to Find Your GCP Project ID 1. In the [Google Cloud Console](https://console.cloud.google.com), look at the project selector at the top of the page. 2. Your **Project ID** is displayed below the project name. It is typically a lowercase string with hyphens (e.g., `my-project-123456`). 3. You can also find it on the **Dashboard** page under **Project info**. Note: The Project ID is different from the Project Name and the Project Number. Make sure you use the Project ID. ## Database ID The Database ID is optional and defaults to `(default)`, which is the standard Firestore database in your project. You only need to specify a Database ID if you are using the Firestore multi-database feature and want to connect to a named database other than the default. Named database IDs can be found in the Google Cloud Console under **Firestore** > **Databases**. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **Google Cloud Firestore**. 3. Paste the contents of your **Service Account JSON** key file. 4. Enter your **GCP Project ID**. 5. Optionally, enter a **Database ID** if you are connecting to a non-default database. 6. Click **Save** to create the connection. ## What Agents Can Do with Firestore Once connected and enabled on an agent, the agent can: - Query documents in a collection with filters (equality, comparison, array membership, etc.) - Retrieve a specific document by its full path (e.g., `users/abc123`) - List all top-level collections in the database - Perform aggregation queries (count, sum, average) on document fields All operations are read-only. Agents cannot create, update, or delete documents. ## Troubleshooting - **Authentication errors**: Verify that the Service Account JSON is complete and correctly pasted. Ensure the service account has not been deleted or disabled. - **Permission denied**: Confirm that the service account has the **Cloud Datastore Viewer** role (`roles/datastore.viewer`). You can check this under **IAM & Admin** > **IAM** in the Google Cloud Console. - **Project not found**: Ensure the GCP Project ID is correct. Use the Project ID (not the Project Name or Project Number). - **Database not found**: If using a non-default database, verify the Database ID matches exactly. Check the database list under **Firestore** > **Databases** in the Google Cloud Console. - **Empty results**: Confirm that the collection you are querying exists and contains documents. Firestore collections are created implicitly when documents are added, so an empty collection will not appear in listings. --- # Google Cloud Logging > Connect Google Cloud Logging to OpsTower for querying GCP application logs, audit logs, and platform logs. > URL: https://docs.opstowerapp.com/connections/gcloud-logging/ Google Cloud Logging provides access to your GCP application logs -- structured JSON logs, audit logs, and platform logs from services like Cloud Run, Cloud Functions, GKE, and App Engine. Connecting it to OpsTower lets your agents query and filter these logs to investigate issues and answer operational questions. ## What This Connection Provides Once connected, agents can: - **Query logs** -- search and filter GCP logs using Cloud Logging filter syntax. - **List resource types** -- discover which GCP resource types are generating logs in your project. Agents construct Cloud Logging filter queries automatically based on your natural language questions. ## Credentials Needed To set up this connection, you will need: 1. **Service Account JSON** -- a Google Cloud service account key file with log reading permissions. 2. **GCP Project ID** -- the identifier of the Google Cloud project whose logs you want to query. 3. **Default Log Filter** (optional) -- a filter expression prepended to all queries to scope results. ## How to Create a GCP Service Account 1. Go to the [Google Cloud Console](https://console.cloud.google.com). 2. Select your project from the project selector dropdown at the top of the page. 3. Navigate to **IAM & Admin** > **Service Accounts** in the left sidebar. 4. Click **Create Service Account**. 5. Enter a name for the service account (e.g., "opstower-logging") and an optional description. 6. Click **Create and Continue**. 7. In the **Grant this service account access to project** step, search for and select the role **Logs Viewer** (`roles/logging.viewer`). 8. Click **Continue**, then click **Done**. 9. Back in the service accounts list, click the service account you just created. 10. Go to the **Keys** tab. 11. Click **Add Key** > **Create new key**. 12. Select **JSON** as the key type and click **Create**. 13. The JSON key file will download automatically. Store it securely -- this file contains credentials that grant access to your GCP logs. When configuring the connection in OpsTower, you will paste the contents of this JSON file. ## How to Find Your GCP Project ID 1. In the [Google Cloud Console](https://console.cloud.google.com), look at the project selector dropdown at the top of the page. 2. Your project ID is displayed below the project name. It is a lowercase string with hyphens (e.g., `my-project-123`). 3. You can also find it by navigating to **Settings** in the left sidebar under your project. ## Default Log Filter (Optional) You can provide a default filter expression that will be prepended to every query the agent runs. This is useful for scoping logs to a specific resource type or service. Examples: - `resource.type="cloud_run_revision"` -- scope to Cloud Run logs only. - `resource.type="cloud_function"` -- scope to Cloud Functions logs only. - `resource.labels.service_name="my-api"` -- scope to a specific Cloud Run service. If you leave this field blank, agents will query across all log entries in the project. ## Setting Up the Connection 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **Google Cloud Logging**. 3. Paste the contents of your **Service Account JSON** key file. 4. Enter your **GCP Project ID**. 5. Optionally enter a **Default Log Filter** to scope queries. 6. Save the connection. Once the connection shows a green status indicator, you can enable it on any Debugger agent to start querying your GCP logs. --- # Generic SQL Connection > Connect any PostgreSQL or MySQL database to OpsTower using a connection string for read-only SQL query access. > URL: https://docs.opstowerapp.com/connections/generic-sql/ The Generic SQL connection allows you to integrate any PostgreSQL or MySQL database with OpsTower using a standard connection string. Agents can run read-only SQL queries against your database for data lookups and analysis. All queries are limited to SELECT statements and return a maximum of 100 rows per query. ## Prerequisites You need a PostgreSQL or MySQL database that is accessible over the network. The database must accept connections from external hosts (or be reachable through a tunnel). ## Credentials Required To set up a Generic SQL connection, you need two pieces of information: - **Connection String** -- a standard database connection URI - **Database Type** -- either PostgreSQL or MySQL ## Connection String Formats ### PostgreSQL ``` postgres://user:password@host:5432/dbname ``` or ``` postgresql://user:password@host:5432/dbname ``` ### MySQL ``` mysql://user:password@host:3306/dbname ``` Replace `user`, `password`, `host`, `5432`/`3306`, and `dbname` with your actual database credentials, host address, port, and database name. ## Security Considerations OpsTower validates all queries as read-only before execution, but it is strongly recommended to create a dedicated read-only database user for the connection. This provides defense in depth. ### Creating a Read-Only User for PostgreSQL ```sql CREATE USER opstower WITH PASSWORD 'your-secure-password'; GRANT CONNECT ON DATABASE your_database TO opstower; GRANT USAGE ON SCHEMA public TO opstower; GRANT SELECT ON ALL TABLES IN SCHEMA public TO opstower; ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO opstower; ``` ### Creating a Read-Only User for MySQL ```sql CREATE USER 'opstower'@'%' IDENTIFIED BY 'your-secure-password'; GRANT SELECT ON your_database.* TO 'opstower'@'%'; FLUSH PRIVILEGES; ``` ### Network Access Ensure your database is accessible from the internet. Common approaches include: - **Cloud-hosted databases** typically provide a public endpoint that you can enable in your provider's settings. - **SSH tunnels** or **VPN connections** may be needed for databases on private networks. - **Firewall rules** should allow inbound connections on the database port from OpsTower's infrastructure. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **Generic SQL**. 3. Select your **Database Type** -- either **PostgreSQL** or **MySQL**. 4. Enter your **Connection String**. 5. Click **Save** to create the connection. ## What Agents Can Do with Generic SQL Once connected and enabled on an agent, the agent can: - Execute read-only SQL queries (SELECT statements only) against your database - List all tables and schemas in the database - Inspect table structures to understand your data model All queries are validated as read-only before execution. Write operations (INSERT, UPDATE, DELETE, DROP, etc.) are rejected. ## Troubleshooting - **Connection refused**: Verify that the host and port in your connection string are correct and that the database is accepting remote connections. - **Authentication failed**: Double-check the username and password in your connection string. Ensure the user exists and has the correct permissions. - **SSL errors**: Some databases require SSL connections. Check your database provider's documentation for SSL connection string parameters (e.g., `?sslmode=require` for PostgreSQL). - **Timeout errors**: Ensure your database is reachable from the internet. If the database is behind a firewall, configure access rules to allow inbound connections. - **Permission denied on tables**: Verify that the database user has SELECT privileges on the tables you want to query. --- # GitHub Connection > Connect GitHub to OpsTower to give your agents access to repository browsing, file reading, code search, and commit history with diffs. > URL: https://docs.opstowerapp.com/connections/github/ The GitHub connection integrates your GitHub repositories with OpsTower, giving agents access to source code and version control data. Agents can browse repositories, read files, search code by pattern, and inspect commit history with full diffs. This is particularly useful for Debugger agents that need to correlate code changes with errors. ## Prerequisites You need a GitHub account with access to the repositories you want to connect. Both public and private repositories are supported, depending on the token scope you configure. ## Credentials Required To set up a GitHub connection, you need one piece of information: - **Personal Access Token (PAT)** -- a token for authenticating requests to the GitHub API ## How to Create a GitHub Personal Access Token GitHub offers two types of personal access tokens. Fine-grained tokens are recommended because they allow you to limit access to specific repositories and grant only the permissions OpsTower needs. ### Option 1: Fine-Grained Token (Recommended) 1. Go to [github.com](https://github.com) and click your profile picture in the top-right corner. 2. Navigate to **Settings** > **Developer settings** > **Personal access tokens** > **Fine-grained tokens**. 3. Click **Generate new token**. 4. Give the token a descriptive name (e.g., "OpsTower"). 5. Set an expiration date. Choose a duration that fits your security requirements. 6. Under **Repository access**, select the repositories you want OpsTower to access, or choose **All repositories** if you want full access. 7. Under **Permissions**, expand **Repository permissions** and grant the following: - **Contents** -- Read access - **Metadata** -- Read access 8. Click **Generate token** and copy the token immediately. It will not be shown again. ### Option 2: Classic Token 1. Go to [github.com](https://github.com) and click your profile picture in the top-right corner. 2. Navigate to **Settings** > **Developer settings** > **Personal access tokens** > **Tokens (classic)**. 3. Click **Generate new token (classic)**. 4. Give the token a descriptive name (e.g., "OpsTower"). 5. Select the appropriate scope: - **`repo`** -- full access to private and public repositories - **`public_repo`** -- access to public repositories only 6. Click **Generate token** and copy the token. Classic tokens start with `ghp_`. Store the token securely. If you lose it, you will need to create a new one. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **GitHub**. 3. Enter your **Personal Access Token**. 4. Click **Save** to create the connection. ## Optional Settings - **Default Branch** -- the branch to use when none is specified in a query. If left empty, OpsTower uses the repository's default branch (typically `main` or `master`). - **Restrict to Repository** -- enter a repository in `owner/repo` format (e.g., `acme/backend`) to limit the connection to a single repository. When set, agents can only access that specific repository through this connection. ## What Agents Can Do with GitHub Once connected and enabled on an agent, the agent can: - **List repositories** -- browse all repositories accessible with the configured token - **Browse file structure** -- navigate directories and list files within a repository - **Read file contents** -- retrieve the full content of any file in a repository - **Search code** -- find code matching a pattern across files in a repository - **List commits** -- view commit history with optional filtering by date range and author - **Get commit details** -- inspect individual commits including full diffs showing what changed ## Usage GitHub connections are primarily used with **Debugger agents**. When investigating errors or incidents, a Debugger agent can use the GitHub connection to correlate code changes with observed issues -- for example, checking recent commits to identify changes that may have introduced a bug. ## Troubleshooting - **Authentication errors**: Verify that your personal access token is correct and has not expired or been revoked. Generate a new token if needed. - **Repository not found**: Confirm that your token has access to the repository in question. For fine-grained tokens, check that the repository is included in the token's repository access list. - **Permission denied on file read**: Ensure your token has **Contents** read permission (fine-grained) or the **repo** scope (classic). - **No commits returned**: Check that the repository has commits on the branch being queried. Verify date range filters if you are using them. --- # GitLab Connection > Connect GitLab to OpsTower to give your agents access to projects, source code, commits, merge requests, and CI/CD pipeline status. > URL: https://docs.opstowerapp.com/connections/gitlab/ The GitLab connection integrates your GitLab account with OpsTower, giving agents the ability to browse projects, read source files, search code, inspect commits and diffs, review merge requests, and monitor pipeline (CI/CD) status. ## Prerequisites You need a GitLab.com account. The connection uses OAuth 2.0 with PKCE, so you authorize OpsTower to access your projects directly from the UI. GitLab's code search uses project-scoped blob search. ## Setup in OpsTower 1. Go to **Connections** > **Code** > **Add Connection**. 2. Select **GitLab**. 3. Click **Connect to GitLab**. 4. A popup opens to GitLab's authorization page. Sign in and grant access. 5. OpsTower automatically discovers your username and stores the connection. 6. Optionally configure: - **Default Branch** -- the default branch for browsing and commits (default: `main`) - **Restrict to Project** -- limit agents to a single project (format: `namespace/project` or `group/subgroup/project`) ## What Agents Can Do Once connected, agents have access to eight tools: - **List Projects** -- discover all projects the connected user has access to, with visibility, default branch, and description - **Browse Repository** -- explore directory structure at any path and branch - **Read File** -- read file contents with line numbers, line range filtering, and binary detection (100KB limit) - **Search Code** -- search for code patterns within a specific project (project-scoped blob search) - **List Commits** -- view recent commits with author, date, and message, filtered by branch or path - **Get Commit** -- inspect a specific commit's details with changed files and diff stats - **List Merge Requests** -- browse MRs by state (opened, closed, merged, all) with author, reviewers, draft status, and comment counts - **List Pipelines** -- monitor CI/CD pipeline runs with status, branch, duration, source, and direct links ## Use Cases - "Show me the most recent commits to the payments service" - "Find all usages of the `processPayment` function in our API project" - "What merge requests are currently open and waiting for review?" - "Read the `src/services/billing.ts` file in our backend project" - "What pipeline runs failed on the main branch today?" - "What changed in commit abc1234?" ## Troubleshooting - **OAuth popup blocked** -- allow popups for the OpsTower domain and try again - **Code search returns no results** -- GitLab code search is project-scoped; make sure to specify the project path - **Pipelines not found (404)** -- pipelines are not enabled for the project, or the project was not found - **Token expired** -- click "Reconnect to GitLab" to refresh the OAuth tokens - **Subgroups** -- GitLab supports nested groups; use the full path like `group/subgroup/project` when restricting access --- # Google Ads Connection > Connect your Google Ads account to OpsTower for campaign management, GAQL-powered metrics, and ad group analysis. > URL: https://docs.opstowerapp.com/connections/google-ads/ The Google Ads connection integrates your Google Ads account with OpsTower via OAuth, giving agents the ability to query campaigns, retrieve performance metrics using GAQL (Google Ads Query Language), and analyze ad groups. ## Prerequisites You need a Google Ads account. If you use a Manager (MCC) account, OpsTower supports querying client accounts through the manager hierarchy. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **Google Ads**. 3. Click **Connect with Google** to start the OAuth flow. 4. Authorize OpsTower and select the Google Ads customer account to connect. 5. You will be redirected back to OpsTower with the connection active. ## What Agents Can Do Once connected and enabled on an agent, the agent can: - **List campaigns** -- view campaigns with status, budget, and campaign type (SEARCH, DISPLAY, PERFORMANCE_MAX, SHOPPING, VIDEO, DEMAND_GEN) - **Query metrics** -- retrieve performance data using GAQL with flexible resource types, date ranges, segments, and validated metrics/ordering - **Get campaign details** -- inspect individual campaigns including their ad groups - **List accounts** -- discover accessible customer accounts All cost values from Google Ads are in micros (divide by 1,000,000 for currency values). ## Important Notes - Always filter `WHERE campaign.status != 'REMOVED'` -- the API returns removed entities by default - WHERE clauses only support AND (no OR) -- for OR logic, agents run multiple queries - Date segments (`segments.date`, `segments.week`, `segments.month`) require a finite date range in WHERE - ROAS is available via `metrics.conversions_value_per_cost` ## Use Cases - **Daily founder report**: Include Google Ads spend, CPA, and ROAS alongside product analytics and organic metrics - **Acquisition analysis**: Correlate ad spend with signup and conversion data from your analytics tools - **Channel comparison**: Compare Google Ads CPA with Meta Ads and organic acquisition channels - **Campaign optimization**: Identify which campaign types and keywords drive the highest-quality users ## Troubleshooting - **Authentication failed**: Re-authorize through the OAuth flow. Google OAuth tokens are refreshed automatically, but the refresh token can be revoked if you remove access in your Google account settings. - **No data returned**: Verify the customer ID is correct. If using a manager account, ensure the manager customer ID is configured. - **Testing mode warning**: New Google Ads API access may be in testing mode for the first 7 days, with limited quota. --- # Intercom Connection > Connect Intercom to OpsTower to give your agents access to conversations, contacts, help center articles, and team management data. > URL: https://docs.opstowerapp.com/connections/intercom/ The Intercom connection integrates your Intercom workspace with OpsTower, giving agents the ability to search conversations, view contact details, browse help center articles, and discover teams and tags. This makes OpsTower a single pane for correlating customer support data with product analytics, error tracking, and other operational signals. ## Prerequisites You need an Intercom workspace with admin access. The connection uses OAuth 2.0, so you authorize OpsTower to access your workspace directly from the UI. Intercom automatically detects your region (US, EU, or AU) and routes API calls accordingly. ## Setup in OpsTower 1. Go to **Connections** > **Customer Support** > **Add Connection**. 2. Select **Intercom**. 3. Click **Connect to Intercom**. 4. A popup opens to Intercom's authorization page. Sign in and grant access. 5. OpsTower automatically discovers your workspace name and region. 6. Optionally add **Support Instructions** to guide how agents search and analyze your support data. ## What Agents Can Do Once connected, agents have access to seven tools: - **Search Conversations** -- search using Intercom's query DSL with field/operator/value objects (state, priority, tags, assignee, rating, etc.) - **Get Conversation** -- view full conversation thread including messages, notes, and performance statistics - **Search Contacts** -- find users and leads by email, name, or custom attributes - **Get Contact** -- view detailed contact information including company, tags, and custom attributes - **List Tags** -- discover tag IDs for filtering conversations - **Search Articles** -- search help center articles for self-service content - **List Teams** -- discover team and admin IDs for filtering by assignee ## Search Examples Agents use Intercom's search DSL to find conversations. Common patterns: - Open conversations: `{"field":"state","operator":"=","value":"open"}` - Priority conversations: `{"field":"priority","operator":"=","value":"priority"}` - AI-handled conversations: `{"field":"ai_agent_participated","operator":"=","value":true}` - Conversations rated 1 or 2: `{"field":"conversation_rating.rating","operator":"<","value":3}` ## Support Instructions You can provide optional instructions that guide how agents search and analyze your Intercom data. For example: > Focus on billing-related conversations. Team 'Billing Support' handles payment issues. Tag 'vip-customer' indicates high-priority contacts. These are injected into the agent's system prompt as preferences. ## Use Cases - "Show me all open priority conversations from the last 7 days" - "What's the average first reply time this month?" - "Find conversations from user john@example.com" - "Search our help center for articles about password reset" - "Which teams have the most open conversations?" - "Show me conversations rated 1 star with comments" --- # Jira Cloud Connection > Connect Jira Cloud to OpsTower to give your agents access to issues, projects, sprints, boards, and automated ticket creation via JQL. > URL: https://docs.opstowerapp.com/connections/jira/ The Jira Cloud connection integrates your Atlassian Jira instance with OpsTower, giving agents the ability to search issues using JQL, view detailed issue information, browse projects and sprints, and create new issues. This makes OpsTower a viable ops layer for teams using Jira alongside or instead of Linear. ## Prerequisites You need a Jira Cloud account (not Jira Server or Data Center). The connection uses OAuth 2.0, so you authorize OpsTower to access your Jira instance directly from the UI. ## Setup in OpsTower 1. Go to **Connections** > **Tickets** > **Add Connection**. 2. Select **Jira**. 3. Click **Connect to Jira**. 4. A popup opens to Atlassian's authorization page. Sign in and grant access. 5. OpsTower automatically discovers your Jira Cloud site and stores the connection. 6. Optionally add **Ticketing Instructions** to guide how agents create and label issues. ## What Agents Can Do Once connected, agents have access to ten tools: - **Search Issues** -- search using JQL (Jira Query Language) with full field filtering - **Get Issue Detail** -- view complete issue details including description (ADF-to-text), comments, and metadata - **List Projects** -- discover all accessible projects and their keys - **List Boards** -- find Scrum and Kanban boards (Jira Software projects) - **List Sprints** -- view active, future, and completed sprints for a board - **Get Sprint Issues** -- list all issues in a sprint with status breakdown - **List Statuses** -- discover valid workflow statuses for a project - **List Users** -- find assignable users and their account IDs - **List Labels** -- browse available labels for JQL filtering - **Create Issue** -- create new issues with project, type, priority, description, assignee, labels, and optional sprint assignment ## JQL Examples Agents use JQL to search Jira issues. Here are common patterns: - `project = ENG ORDER BY updated DESC` -- recent issues in a project - `assignee = currentUser() AND sprint in openSprints()` -- your current sprint work - `priority = High AND created >= -7d AND status != Done` -- recent high-priority issues - `issuetype = Bug AND status != Done ORDER BY priority ASC` -- open bugs by priority ## Ticketing Instructions You can provide optional instructions that guide how agents create and manage issues. For example: > Always use project ENG for engineering bugs. Set priority to High for production issues. Add the label "ops-created" to all auto-created tickets. These are injected into the agent's system prompt as preferences, but agents will still confirm details with you before creating issues. ## Use Cases - "What tickets are assigned to me in the current sprint?" - "Show me all open P1 bugs in the PLATFORM project" - "Create a Jira ticket for the login error we found in Sentry" - "Which sprint is currently active for the backend team?" - "What's the status breakdown of issues in the ENG project?" ## Troubleshooting - **OAuth popup blocked** -- allow popups for the OpsTower domain and try again - **No Jira sites found** -- ensure your Atlassian account has access to at least one Jira Cloud site - **Boards/sprints not available** -- boards and sprints require Jira Software projects (not Jira Work Management or Service Management) - **Token expired** -- click "Reconnect to Jira" to refresh the OAuth tokens --- # Linear Connection > Connect Linear to OpsTower to give your agents the ability to search issues, view details, and create new tickets automatically. > URL: https://docs.opstowerapp.com/connections/linear/ The Linear connection integrates your Linear workspace with OpsTower, giving agents the ability to search issues, view issue details with comments, list teams and labels, and create new issues. This is OpsTower's first ticketing integration, enabling automated issue creation from systems operations reports. ## Prerequisites You need a Linear account with an active workspace. Any Linear plan that supports API access will work. ## Credentials Required To set up a Linear connection, you need: - **API Key** -- a personal API key from your Linear account (starts with `lin_api_`) ## How to Create an API Key 1. In Linear, go to **Settings** > **Preferences** > **Security & Access**. 2. Under **Personal API keys**, click **Create key**. 3. Give it a descriptive label (e.g., "OpsTower"). 4. Copy the generated key (starts with `lin_api_`) and paste it into OpsTower. API keys inherit the permissions of the user who creates them. The key can access all teams and projects the user has access to. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **Linear** from the Tickets category. 3. Enter your **API Key**. 4. Optionally add **Ticketing Instructions** -- custom guidance for agents when creating or searching tickets (e.g., default team, labels, priority rules). 5. Click **Test Connection** to verify your credentials. 6. Click **Save** to create the connection. ## Ticketing Instructions The Ticketing Instructions field is a free-text area (up to 2000 characters) where you can provide custom guidance for agents. This is injected into the agent's context when it uses the Linear tools. Examples: - "Always assign bugs to the Engineering team using label 'from-opstower'." - "Default priority should be Medium unless the issue affects payments." - "Use the ENG team for backend issues and the FE team for frontend issues." These instructions help agents follow your team's conventions when creating tickets. ## What Agents Can Do with Linear Once connected and enabled on an agent, the agent can: - **Search issues** -- filter issues by team, state type, label, and more - **Get issue details** -- retrieve a specific issue by identifier (e.g., ENG-123) with full description, comments, labels, and assignee - **List teams** -- discover available teams with their keys and member counts - **List labels** -- discover available labels for tagging issues - **Create issues** -- file new issues with title, description, team, priority, labels, and assignee When creating issues, agents are instructed to confirm with the user first (in chat mode) or follow the auto-ticketing configuration (in report mode). ## Auto-Ticketing in Reports When a Linear connection is added to a Systems Operations report's data sources, you can enable auto-ticketing. The report agent will automatically create Linear tickets for issues discovered during the report run. You can configure: - **Scope: All issues** -- create tickets for every issue found - **Scope: Code-related only** -- create tickets only for issues classified as code bugs Tickets include the issue classification, severity, relevant log excerpts, and a link back to the report. See [Reports Overview](/reports/overview/) for more details. ## Troubleshooting - **Authentication failed**: Verify your API key is correct and starts with `lin_api_`. Ensure the key has not been revoked in Linear's settings. - **No teams found**: The API key inherits your user permissions. Make sure your Linear account has access to at least one team. - **Issue creation failed**: Ensure you are providing a valid team ID. Use the list teams tool first to discover available team IDs. - **Ticketing instructions not applied**: Instructions are injected into the agent's system prompt. They guide the agent's behavior but are not hard constraints -- the agent uses its judgment to apply them contextually. --- # LinkedIn Connection > Connect your LinkedIn account to OpsTower so agents can analyze post performance and engagement metrics. > URL: https://docs.opstowerapp.com/connections/linkedin/ The LinkedIn connection integrates your account with OpsTower via OAuth, giving agents the ability to pull recent posts and analyze engagement analytics. ## Prerequisites You need a LinkedIn account. The connection uses OAuth 2.0 for secure authorization. ## Important Note LinkedIn access tokens expire after 60 days. When the token expires, you will need to reconnect by re-authorizing through the OAuth flow. OpsTower will display a warning when the token is approaching expiration. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **LinkedIn**. 3. Click **Connect with LinkedIn** to start the OAuth flow. 4. Authorize OpsTower in the LinkedIn consent screen. 5. You will be redirected back to OpsTower with the connection active. ## What Agents Can Do Once connected and enabled on an agent, the agent can: - **List recent posts** -- pull your recent LinkedIn posts and their content - **Get post analytics** -- retrieve engagement metrics for specific posts ## Use Cases - **Content strategy**: Understand which post types (product announcements, thought leadership, customer stories) drive the most engagement - **Social attribution**: Correlate LinkedIn post engagement with traffic and signup spikes in your analytics - **Audience insights**: Track how your professional audience responds to different content themes --- # Meta Ads Connection > Connect your Meta Ads account (Facebook + Instagram) to OpsTower for campaign performance, spend analytics, and audience breakdowns. > URL: https://docs.opstowerapp.com/connections/meta-ads/ The Meta Ads connection integrates your Facebook/Instagram ad account with OpsTower via OAuth, giving agents the ability to list campaigns, query performance insights, and break down metrics by audience segments. ## Prerequisites You need a Meta Business account with at least one ad account. The connection uses OAuth 2.0 for secure authorization. ## Important Note Meta access tokens expire after approximately 60 days. When the token expires, you will need to reconnect by re-authorizing through the OAuth flow. OpsTower will display a warning when the token is approaching expiration. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **Meta Ads**. 3. Click **Connect with Facebook** to start the OAuth flow. 4. Authorize OpsTower and select the ad account you want to connect. 5. You will be redirected back to OpsTower with the connection active. ## What Agents Can Do Once connected and enabled on an agent, the agent can: - **List campaigns** -- view campaigns with their status, budget remaining, and objectives - **Query performance insights** -- retrieve metrics including impressions, reach, spend, clicks, CTR, CPC, CPM, and ROAS - **Get campaign details** -- inspect individual campaign configuration and ad groups - **List ad accounts** -- discover all ad accounts you have access to - **Break down by audience** -- segment metrics by age, gender, country, region, device platform, publisher platform (Facebook vs Instagram), and placement ## Use Cases - **Daily founder report**: Include ad spend, ROAS, and campaign performance alongside product analytics - **Acquisition analysis**: Correlate Meta Ads spend with signup and conversion data from your analytics tools - **Platform comparison**: Compare Facebook vs Instagram ad performance using publisher_platform breakdowns - **Budget optimization**: Identify which campaigns and audiences drive the highest-quality users ## Troubleshooting - **Token expired**: Meta tokens last approximately 60 days. Reconnect through the connection settings page. - **No ad accounts found**: Your Facebook user must have access to at least one ad account in Meta Business Manager. - **Reach unavailable**: Reach metrics are not available for queries with breakdowns and start dates older than 13 months. --- # Facebook & Instagram Connection > Connect your Facebook Page and Instagram account to OpsTower for post analytics, page insights, and media performance data. > URL: https://docs.opstowerapp.com/connections/meta-social/ The Facebook & Instagram connection integrates your Facebook Page (and optionally linked Instagram account) with OpsTower via OAuth. Agents can pull posts, page-level insights, and Instagram media analytics. ## Prerequisites You need a Facebook Page that you manage. If you also want Instagram analytics, your Instagram Business or Creator account must be linked to your Facebook Page. ## Token Handling This connection uses a Page Access Token, which does not expire. Unlike other OAuth connections, you will not need to periodically re-authorize. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **Facebook & Instagram**. 3. Click **Connect with Facebook** to start the OAuth flow. 4. Authorize OpsTower and select the Facebook Page you want to connect. 5. You will be redirected back to OpsTower with the connection active. ## What Agents Can Do ### Facebook Page - **List page posts** -- pull recent published posts with engagement summaries (likes, comments, shares) - **Get post insights** -- retrieve detailed post metrics (impressions, engaged users, clicks, reactions) - **Get page insights** -- query page-level metrics over time (impressions, fans, page views) with day, week, or 28-day periods ### Instagram (when linked) - **List media** -- pull recent Instagram posts with captions, media types, likes, and comments - **Get media insights** -- retrieve detailed media metrics (impressions, reach, saves, shares) that vary by media type (IMAGE, VIDEO, REEL, CAROUSEL_ALBUM) - **Get account insights** -- query account-level metrics (impressions, reach, follower count, profile views) with day, week, or 28-day periods ## Use Cases - **Social attribution**: Correlate a high-engagement Facebook post or Instagram reel with a traffic spike in your analytics - **Content strategy**: Compare engagement across content types and platforms to understand what drives business outcomes - **Audience growth**: Track page fan growth and Instagram follower trends alongside product metrics --- # Mixpanel Connection > Connect Mixpanel to OpsTower to give your agents access to event analytics, funnels, retention, and segmentation data. > URL: https://docs.opstowerapp.com/connections/mixpanel/ The Mixpanel connection integrates your Mixpanel project with OpsTower, giving agents access to event analytics data including event trends, funnels, retention cohorts, and segmentation breakdowns. Once connected, you can use Mixpanel data in scheduled reports and in agent chat queries. ## Prerequisites You need a Mixpanel account with access to the project you want to connect. You will also need the ability to create Service Accounts in your Mixpanel organization settings. ## Credentials Required To set up a Mixpanel connection, you need three pieces of information: - **Service Account Username** -- the username for a Mixpanel Service Account - **Service Account Secret** -- the secret for the Service Account (shown only at creation time) - **Project ID** -- the numeric identifier for the Mixpanel project to query You also need to select your **Data Residency Region** (United States, Europe, or India) to match where your Mixpanel data is stored. ## How to Create a Mixpanel Service Account 1. Log in to Mixpanel at [mixpanel.com](https://mixpanel.com). 2. Click the gear icon in the top bar to open **Organization Settings**. 3. In the left sidebar, click **Service Accounts**. 4. Click **Add Service Account**. 5. Give the service account a descriptive name (e.g., "OpsTower"). 6. Select a role with **read access** to the project you want to connect. A "Viewer" or "Analyst" role is sufficient. 7. Under project access, grant the service account access to the specific project(s) you want to query. 8. Click **Create**. 9. Copy the **Username** and **Secret** immediately -- the secret is only shown once and cannot be recovered later. Store these credentials securely. If you lose the secret, you will need to create a new service account. ## How to Find Your Project ID 1. In Mixpanel, click the gear icon and navigate to your project settings. 2. Under the **Access Keys** section, the **Project ID** is displayed as a numeric value. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **Mixpanel**. 3. Enter your **Service Account Username**, **Service Account Secret**, and **Project ID**. 4. Select your **Data Residency Region** (US, EU, or India) to match where your Mixpanel data is hosted. 5. Optionally, add a **Custom Analytics Prompt** -- additional instructions for how the agent should analyze your Mixpanel data (max 2000 characters). For example, you might specify which events are most important, key funnels to track, or metrics to prioritize. 6. Click **Test Connection** to verify your credentials are valid. 7. Click **Save** to create the connection. ## What Agents Can Do with Mixpanel Once connected and enabled on an agent, the agent can: - Query event segmentation data with daily, weekly, or monthly breakdowns - List and analyze top events by volume - Query funnel conversion data for saved funnels - Analyze retention cohorts to measure user return rates - Retrieve saved Insights reports - Generate scheduled analytics reports with trend analysis and anomaly detection ## Usage Mixpanel connections are used in two primary contexts: - **Scheduled Reports** -- automated analytics summaries delivered on a recurring schedule, covering key metrics, period-over-period comparisons, and detected anomalies. - **Agent Chat** -- real-time queries during conversations with your agents, where the agent calls Mixpanel's API to fetch and analyze data on demand. ## Data Residency Mixpanel stores data in region-specific data centers. When setting up your connection, select the region that matches your Mixpanel project's data residency: | Region | Description | | ------ | ----------------------- | | US | United States (default) | | EU | European Union | | India | India | Using the wrong region will result in authentication errors, since your credentials are scoped to the region where your data is stored. ## Rate Limits Mixpanel's Query API allows 60 queries per hour and 5 concurrent queries. OpsTower's daily reports typically make 10-20 queries, which is well within these limits. If you encounter rate limit errors, space out report generation across your connections. ## Troubleshooting - **Authentication errors**: Verify that your Service Account credentials are correct and the service account has not been deleted. Ensure the selected region matches your Mixpanel project's data residency. - **Permission errors**: Confirm that the Service Account has been granted access to the specific project you are trying to query. Check the role permissions in Mixpanel Organization Settings. - **No data returned**: Confirm that the Project ID is correct and the project has recent events ingested. - **Rate limit errors**: Mixpanel allows 60 queries per hour. If you have multiple connections generating reports simultaneously, consider staggering their schedules. --- # MongoDB Connection > Connect your MongoDB database to OpsTower to give your agents read-only query access for document lookups, aggregations, and data analysis. > URL: https://docs.opstowerapp.com/connections/mongodb/ The MongoDB connection integrates your MongoDB database with OpsTower, giving agents the ability to run read-only find and aggregate queries against your collections. All queries return results capped at 100 documents per query. ## Prerequisites You need a MongoDB instance that is accessible over the internet. MongoDB Atlas, self-hosted instances, and managed providers (Railway, Render, etc.) are all supported. ## Credentials Required To set up a MongoDB connection, you need the following: - **Connection String** -- a standard MongoDB connection URI (`mongodb://` or `mongodb+srv://`) - **Database** (optional) -- the default database name for queries (overrides the database specified in the connection string) ## How to Find Your Connection String ### MongoDB Atlas 1. Log in to [cloud.mongodb.com](https://cloud.mongodb.com) and open your cluster. 2. Click **Connect** in the cluster overview. 3. Select **Drivers** as the connection method. 4. Copy the connection string. It will look like: `mongodb+srv://username:password@cluster0.abc123.mongodb.net/mydb` 5. Replace `` with your database user's actual password. ### Self-Hosted Use the standard MongoDB connection string format: ``` mongodb://username:password@host:27017/database ``` ### Railway / Render / Other Providers Copy the MongoDB connection string from your provider's dashboard. It is usually found in the service's connection or environment variables section. ## Network Access (Atlas) Cloudflare Workers run across a global network of data centers and do not have fixed IP addresses. If you are using MongoDB Atlas, you must configure your network access to allow connections from any IP address. 1. In the Atlas dashboard, go to **Network Access** in the left sidebar. 2. Click **Add IP Address**. 3. Click **Allow Access from Anywhere**, which sets the allowlist to `0.0.0.0/0`. 4. Click **Confirm**. Your connection is still secured by username/password authentication and TLS encryption in transit. The IP allowlist is an additional layer, not the primary security mechanism. ## Security Considerations OpsTower only runs read-only operations against your MongoDB database. Agents use `find` (with filters, projections, and sort) and `aggregate` (with pipelines) -- no insert, update, or delete operations are performed. For additional safety, create a dedicated read-only user for OpsTower: ```javascript db.createUser({ user: "opstower", pwd: "your-secure-password", roles: [{ role: "read", db: "your_database" }] }); ``` This ensures that even if OpsTower's query restrictions were somehow bypassed, the database user itself cannot perform mutations. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **MongoDB**. 3. Enter your **Connection String**. 4. Optionally specify a **Database** name (leave blank to use the database from the connection string). 5. Click **Test Connection** to verify your credentials. 6. Click **Save** to create the connection. ## What Agents Can Do with MongoDB Once connected and enabled on an agent, the agent can: - Run `find` queries with filters, projections, sorting, and limits - Run `aggregate` pipelines with stages like `$match`, `$group`, `$sort`, `$project`, `$unwind`, and `$lookup` - List all collections in the database with document counts and sample field structures - Reference the [MongoDB query operator docs](https://www.mongodb.com/docs/manual/reference/operator/query/) for syntax help Agents are guided to use `list_collections` first to discover available data, then write targeted queries. The tool descriptions include links to MongoDB documentation so agents can self-serve when encountering unfamiliar query patterns. ## Troubleshooting - **Connection refused / timeout**: Verify that your MongoDB instance is reachable from the internet. For Atlas, ensure you have set Network Access to Allow Access from Anywhere (`0.0.0.0/0`). - **Authentication failed**: Double-check the username and password in your connection string. Ensure the user exists and has read access to the target database. - **Database not found**: If you specified a database name, verify that it exists. You can leave the database field blank to use the default from the connection string. - **"not primary" or replica set errors**: Ensure your connection string includes the full replica set URI. For Atlas, always use the `mongodb+srv://` format. - **Slow queries**: MongoDB agents are capped at 100 documents per query. Use specific filters and projections to narrow results. For aggregation, add `$match` stages early in the pipeline to reduce the working set. --- # Connections Overview > Learn how connections integrate external services with your OpsTower agents, providing access to analytics, logs, databases, and code repositories. > URL: https://docs.opstowerapp.com/connections/overview/ Connections are integrations to external services that provide data to your agents. Each connection links OpsTower to a specific platform -- such as an analytics tool, a logging service, a database, or a code repository -- so that agents can query real data when answering your questions or generating reports. You manage connections from the **Connections** page in the OpsTower dashboard. Once a connection is created, you can enable it on one or more agents to give them access to that data source. ## Connection Categories OpsTower supports twelve categories of connections, each serving a different purpose. ### Analytics Analytics connections provide product analytics data -- events, metrics, user behavior, feature flags, experiments, and more. | Service | Description | | --------- | --------------------------------------------------------- | | PostHog | Product analytics, feature flags, error tracking | | Amplitude | Product analytics, charts, dashboards, cohorts | | GA4 | Web and app analytics via Google Analytics 4 | | Mixpanel | Event analytics with funnels, retention, and segmentation | ### Error Tracking Error tracking connections provide grouped error data with stack traces, frequency trends, and release health metrics. | Service | Description | | ------- | ----------------------------------------------------------------- | | Sentry | Application error monitoring with issue grouping and stack traces | ### Payments Payment connections provide revenue analytics, subscription data, and payment health metrics. | Service | Description | | --------- | ------------------------------------------------------------------ | | Stripe | Subscriptions, revenue, charges, and invoices | | Paddle | Subscriptions, transactions, customers, and product catalog | | Chargebee | Subscriptions, invoices, customers, transactions, and pricing catalog | | Braintree | Transactions (GraphQL), subscriptions, disputes, and customer vault | ### Logs Logs connections provide application logs and observability data for investigating errors, performance issues, and system behavior. | Service | Description | | -------------------- | ----------------------------------------- | | Axiom | Log management and observability | | Cloudflare Logging | Edge and application logs from Cloudflare | | Google Cloud Logging | Centralized logging for GCP workloads | | AWS CloudWatch | Logs and metrics for AWS resources | ### Databases Database connections allow agents to run read-only queries against your databases, enabling direct data lookups and analysis. | Service | Description | | ---------------- | ----------------------------------------------------------- | | ClickHouse | Columnar analytics database for real-time queries | | Cloudflare D1 | Serverless SQLite databases on Cloudflare | | Supabase | Postgres databases managed by Supabase | | Generic SQL | Any PostgreSQL or MySQL database via connection string | | AWS DynamoDB | NoSQL key-value and document database on AWS | | MongoDB | Document database (Atlas, self-hosted, and other providers) | | Google Firestore | NoSQL document database on Google Cloud | ### Ticketing Ticketing connections let agents search, view, and create issues in your project management tools. This enables both interactive ticket management from chat and automated issue creation from systems operations reports. | Service | Description | | ---------- | ------------------------------------------------------------------------ | | Linear | Issue search, detail view, team/label discovery, and ticket creation | | Jira Cloud | JQL search, issue detail, projects, boards, sprints, and issue creation | ### Code Code connections give agents access to your source code, enabling repository browsing, code search, and commit history review. | Service | Description | | --------------- | ------------------------------------------------------------------------ | | GitHub | Repository browsing, code search, commit history | | Bitbucket Cloud | Repository browsing, code search, commits, pull requests, and pipelines | | GitLab | Project browsing, code search, commits, merge requests, and pipelines | ### Social Social connections provide engagement metrics and audience insights from your social media accounts, correlated with product analytics. | Service | Description | | -------------------- | --------------------------------------------------------- | | X (Twitter) | Tweets, engagement metrics, and mentions | | LinkedIn | Posts and engagement analytics | | Facebook & Instagram | Page posts, page insights, Instagram media and account insights | ### Advertising Advertising connections provide campaign performance, ad spend, and return on ad spend (ROAS) metrics to connect paid acquisition with product outcomes. | Service | Description | | ------------------------------ | ---------------------------------------------------- | | Meta Ads (Facebook + Instagram)| Campaign management, performance insights, breakdowns| | Google Ads | Campaigns, GAQL metrics, ad groups, and account listing| ### App Stores App store connections provide access to app reviews, ratings, and metadata from mobile app distribution platforms. | Service | Description | | ------------------ | --------------------------------------------------- | | App Store Connect | iOS and macOS app reviews, ratings, and app metadata | ### Customer Support Customer support connections give agents access to support tickets, conversations, CSAT ratings, help center articles, and performance metrics. Agents can search and analyze support data to correlate customer issues with product analytics and error tracking signals. | Service | Description | | -------- | -------------------------------------------------------------------------- | | Intercom | Conversations, contacts, help center articles, tags, and team management | | Zendesk | Tickets (ZQL search), CSAT ratings, ticket metrics, help center, and views | ### External APIs External API connections let you integrate any REST API that OpsTower does not have a dedicated integration for. Provide a base URL, authentication credentials, and optional documentation context -- agents handle the rest. | Service | Description | | ------------ | ---------------------------------------------------------------- | | External API | Connect any REST API with Bearer, API key, Basic Auth, or query parameter authentication | ## Agent Type Compatibility Not every agent type can use every category of connection. The table below shows which categories are available for each agent type. | Agent Type | Analytics | Error Tracking | Payments | Logs | Databases | Ticketing | Code | Social | Advertising | App Stores | Support | External APIs | | --------------- | --------- | -------------- | -------- | ---- | --------- | --------- | ---- | ------ | ----------- | ---------- | ------- | ------------- | | Debugger | | Yes | | Yes | Yes | Yes | Yes | | | | Yes | Yes | | Analyst | Yes | | Yes | | Yes | | | Yes | Yes | Yes | Yes | Yes | | Product Manager | Yes | Yes | Yes | | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | | Custom | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | **Debugger** agents are designed for investigating issues, so they have access to error tracking, logs, code, databases, ticketing, and external APIs -- the tools you need to trace, resolve, and track problems. **Analyst** agents focus on understanding product performance and user behavior, so they have access to analytics platforms, payment providers, databases, social media, advertising, and external APIs for deeper data exploration. **Product Manager** agents combine analytics, errors, payments, ticketing, code, databases, social media, advertising, and external APIs to help you understand product performance and make data-driven decisions. **Custom** agents have access to all connection categories, making them suitable for any operational task. ## Security All connection credentials are encrypted at rest using AES-GCM encryption. OpsTower never stores plaintext secrets. Database connections are read-only by design, ensuring that agents cannot modify your data. ## Plan Limits The number of connections you can create depends on your subscription tier. | Plan | Connection Limit | | -------- | ---------------- | | Free | 4 | | Pro | 15 | | Business | Unlimited | If you reach your plan's limit, you can upgrade from the billing settings page or remove an existing connection to free up a slot. ## Next Steps - [PostHog Connection](/connections/posthog/) -- connect your PostHog project for product analytics - [Amplitude Connection](/connections/amplitude/) -- connect Amplitude via OAuth - [GA4 Connection](/connections/ga4/) -- connect Google Analytics 4 with a service account - [Mixpanel Connection](/connections/mixpanel/) -- connect Mixpanel with a Service Account - [Sentry Connection](/connections/sentry/) -- connect Sentry for error tracking with stack traces - [Stripe Connection](/connections/stripe/) -- connect Stripe for subscription and revenue analytics - [Paddle Connection](/connections/paddle/) -- connect Paddle Billing for subscription and transaction analytics - [Chargebee Connection](/connections/chargebee/) -- connect Chargebee for subscription billing and revenue management - [Braintree Connection](/connections/braintree/) -- connect Braintree for transaction, subscription, and dispute analytics - [MongoDB Connection](/connections/mongodb/) -- connect a MongoDB database (Atlas, self-hosted, or other providers) - [Linear Connection](/connections/linear/) -- connect Linear for ticket search, tracking, and automated issue creation - [Jira Cloud Connection](/connections/jira/) -- connect Jira Cloud for issue search, sprints, and automated ticket creation - [ClickHouse Connection](/connections/clickhouse/) -- connect a ClickHouse database for columnar analytics queries - [Supabase Connection](/connections/supabase/) -- connect your Supabase PostgreSQL database - [X (Twitter) Connection](/connections/x-twitter/) -- connect X for tweet analytics and mentions - [LinkedIn Connection](/connections/linkedin/) -- connect LinkedIn for post engagement analytics - [Facebook & Instagram Connection](/connections/meta-social/) -- connect your Facebook Page and Instagram for post and page insights - [Meta Ads Connection](/connections/meta-ads/) -- connect Meta Ads for campaign performance and spend analytics - [Google Ads Connection](/connections/google-ads/) -- connect Google Ads for campaign metrics and GAQL queries - [Bitbucket Cloud Connection](/connections/bitbucket/) -- connect Bitbucket for source code, pull requests, and pipeline monitoring - [GitLab Connection](/connections/gitlab/) -- connect GitLab for source code, merge requests, and pipeline monitoring - [App Store Connect Connection](/connections/app-store-connect/) -- connect Apple App Store Connect for app reviews, ratings, and metadata - [Intercom Connection](/connections/intercom/) -- connect Intercom for customer support conversations, contacts, and help center - [Zendesk Connection](/connections/zendesk/) -- connect Zendesk for support tickets, CSAT ratings, and performance metrics - [External API Connection](/connections/external-api/) -- connect any REST API with flexible authentication --- # Paddle Connection > Connect Paddle Billing to OpsTower to give your agents access to subscription data, transaction analytics, customer details, and product catalogs. > URL: https://docs.opstowerapp.com/connections/paddle/ The Paddle Billing connection integrates your Paddle account with OpsTower, giving agents the ability to query subscriptions, analyze transactions and revenue, review customers, and inspect your product catalog. All operations are read-only. ## Prerequisites You need a Paddle Billing account with API access. Both production and sandbox environments are supported. This integration works with Paddle Billing (v2 API) only -- Paddle Classic is not supported. ## Credentials Required To set up a Paddle connection, you need: - **API Key** -- a Paddle API key with read permissions - **Environment** -- whether the key is for production or sandbox ## How to Create a Paddle API Key 1. In your Paddle Dashboard, go to **Developer Tools** > **Authentication**. 2. Click **Generate API Key**. 3. Name it something like "OpsTower Read Only". 4. Set **Read** permission for the following resources: - **Subscriptions** -- for MRR, churn, and subscription health analysis - **Transactions** -- for revenue and payment tracking - **Customers** -- for customer context and search - **Products** and **Prices** -- for product catalog reference 5. Set **None** for all write operations. 6. Click **Generate** and copy the key. Production keys start with `pdl_live_` and sandbox keys start with `pdl_sdbx_`. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **Paddle**. 3. Select your **Environment** (Production or Sandbox). 4. Enter your **API Key**. 5. Click **Test Connection** to verify your credentials. 6. Click **Save** to create the connection. ## What Agents Can Do with Paddle Once connected and enabled on an agent, the agent can: - **Query subscriptions** -- list active, canceled, past-due, paused, and trialing subscriptions with automatic MRR calculation, billing cycle details, and item breakdowns - **Query transactions** -- analyze completed transactions for revenue totals including subtotal, tax, discounts, fees, and net earnings over any time range - **Query customers** -- search and list customers by email, name, or status - **Query products** -- inspect your product catalog with pricing tiers and billing cycles All monetary amounts from Paddle are in the smallest currency unit (e.g., cents for USD). Agents automatically convert these to readable amounts in their responses. ## Use Cases - **Daily founder report**: Include MRR, new subscriptions, churn, and transaction volume alongside product analytics - **Revenue investigation**: "Why did MRR drop this week?" -- the agent queries canceled subscriptions and correlates with product data - **Customer analysis**: Search for specific customers and see their subscription status and transaction history - **Product catalog review**: Understand pricing structure and active vs archived products ## Troubleshooting - **Authentication failed**: Verify your API key is correct. Production keys start with `pdl_live_` and sandbox keys with `pdl_sdbx_`. - **Environment mismatch**: Using a sandbox key against the production API (or vice versa) returns a 403 error. Make sure the environment setting matches your key type. - **No data returned**: If using a sandbox key, only sandbox test data will be returned. Switch to a production key for live data. - **Rate limited**: Paddle allows 240 requests per minute. OpsTower's periodic queries are well within this limit. If you see a 429 error, the agent will retry automatically. --- # PostHog Connection > Connect PostHog to OpsTower to give your agents access to product analytics events, metrics, feature flags, experiments, and error tracking. > URL: https://docs.opstowerapp.com/connections/posthog/ The PostHog connection integrates your PostHog project with OpsTower, giving agents access to product analytics data including events, metrics, feature flags, experiments, and error tracking. Once connected, you can use PostHog data in scheduled reports and in agent chat queries via MCP (Model Context Protocol). ## Prerequisites You need a PostHog account with access to the project you want to connect. PostHog Cloud (app.posthog.com) and self-hosted instances are both supported. ## Credentials Required To set up a PostHog connection, you need two pieces of information: - **API Key** -- a personal API key for authenticating requests - **Project ID** -- the identifier for the specific PostHog project to query ## How to Get Your PostHog API Key 1. Log in to PostHog at [app.posthog.com](https://app.posthog.com) (or your self-hosted instance). 2. Click your profile icon in the bottom-left corner. 3. Go to **Personal API Keys**. 4. Click **Create personal API key**. 5. Give the key a descriptive name (e.g., "OpsTower"). 6. Select the required scopes. At minimum: `query:read` and `project:read`. For full functionality, also enable: `insight:read`, `action:read`, `feature_flag:read`, `experiment:read`, and `error_tracking:read`. 7. Copy the key immediately -- it starts with `phx_` and will not be shown again. Store this key securely. If you lose it, you will need to create a new one. ## How to Find Your Project ID 1. In PostHog, go to **Project Settings** (click the gear icon or navigate via the sidebar). 2. The Project ID is displayed at the top of the settings page. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **PostHog**. 3. Enter your **API Key** and **Project ID**. 4. Optionally, add a **Custom Analytics Prompt** -- additional instructions for how the agent should analyze your PostHog data (max 2000 characters). For example, you might specify which events are most important, how to interpret custom properties, or which metrics to prioritize. 5. Click **Save** to create the connection. ## What Agents Can Do with PostHog Once connected and enabled on an agent, the agent can: - Query event data and compute metrics over time ranges - Look up feature flag configurations and rollout status - Review experiment results and statistical significance - Investigate error tracking data - Generate scheduled analytics reports with trend analysis and anomaly detection ## Usage PostHog connections are used in two primary contexts: - **Scheduled Reports** -- automated analytics summaries delivered on a recurring schedule, covering key metrics, period-over-period comparisons, and detected anomalies. - **Agent Chat via MCP** -- real-time queries during conversations with your agents, where the agent calls PostHog through the Model Context Protocol to fetch and analyze data on demand. ## Troubleshooting - **Authentication errors**: Verify that your API key is correct and has not been revoked. Generate a new key if needed. - **No data returned**: Confirm that the Project ID matches the project containing your data. Check that the project has recent events ingested. - **Self-hosted instances**: Ensure your PostHog instance is reachable from the internet, or check your network configuration if you are on a private network. --- # Sentry Connection > Connect Sentry to OpsTower to give your agents access to error tracking data, issue details with stack traces, and error volume trends. > URL: https://docs.opstowerapp.com/connections/sentry/ The Sentry connection integrates your Sentry organization with OpsTower, giving agents the ability to query issues, view error events with full stack traces, analyze error volume trends, and discover projects. ## Prerequisites You need a Sentry account with at least one project. Both sentry.io (cloud) and self-hosted Sentry instances are supported. ## Credentials Required To set up a Sentry connection, you need the following: - **Auth Token** -- an Internal Integration token with read-only permissions - **Organization Slug** -- your Sentry organization identifier (found in your Sentry URL) - **Project Slugs** (optional) -- comma-separated project slugs to scope queries to specific projects ## How to Create an Auth Token 1. In Sentry, go to **Settings** > **Developer Settings** > **Custom Integrations**. 2. Click **Create New Integration** > **Internal Integration**. 3. Give it a name (e.g., "OpsTower Read Only"). 4. Set permissions to **Read** for: - **Organization** -- to list organization details and stats - **Project** -- to list projects and their error events - **Issue & Event** -- to list issues and retrieve events with stack traces 5. Scroll to the bottom and click **New Token** to generate a token. 6. Copy the generated token and paste it into OpsTower. Internal Integration tokens never expire and must be manually revoked. ## Finding Your Organization Slug Your organization slug is the identifier in your Sentry URL: ``` https://your-org-slug.sentry.io ``` For example, if your Sentry URL is `https://my-startup.sentry.io`, your organization slug is `my-startup`. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **Sentry**. 3. Enter your **Auth Token** and **Organization Slug**. 4. Optionally enter **Project Slugs** to scope queries (leave blank to search all projects). 5. Click **Test Connection** to verify your credentials. 6. Click **Save** to create the connection. ## What Agents Can Do with Sentry Once connected and enabled on an agent, the agent can: - **Query issues** -- list grouped errors with severity level, occurrence count, affected users, first/last seen times, and direct links to Sentry - **Get issue events** -- retrieve individual error occurrences with full stack traces, exception details, breadcrumbs, and user context - **Query error stats** -- analyze error volume trends over time, grouped by outcome (accepted/filtered/rate-limited) or by project - **List projects** -- discover all projects in the organization with platform and creation date Agents are guided to use `list_projects` first to discover available projects, then query issues sorted by frequency or date to find the most impactful errors. ## Troubleshooting - **Authentication failed**: Verify your auth token is correct and has not been revoked. Ensure the Internal Integration has Read permissions for Organization, Project, and Issue & Event. - **Organization not found**: Double-check your organization slug. It must exactly match the slug in your Sentry URL (lowercase, hyphens allowed). - **No issues returned**: Try broadening your query. The default filter is `is:unresolved` -- use an empty query string to search all statuses. Check that the token has access to the projects you are querying. - **Rate limited**: Sentry applies per-endpoint rate limits. If you see rate limit errors, reduce the frequency of queries. The rate limit headers (`X-Sentry-Rate-Limit-Remaining`) indicate how many requests remain. --- # Stripe Connection > Connect Stripe to OpsTower to give your agents access to subscription data, revenue analytics, charges, and invoices. > URL: https://docs.opstowerapp.com/connections/stripe/ The Stripe connection integrates your Stripe account with OpsTower, giving agents the ability to query subscriptions, analyze revenue, review charges, and inspect invoices. All operations are read-only. ## Prerequisites You need a Stripe account with API access. Both live mode and test mode keys are supported. ## Credentials Required To set up a Stripe connection, you need: - **API Key** -- a restricted API key with read-only permissions (recommended) or a secret key ## How to Create a Restricted API Key For best security, create a restricted key that only has read access: 1. In your Stripe account, go to **Settings** > **Developers** > **API Keys**. 2. Click **Create restricted key**. 3. Name it something like "OpsTower Read Only". 4. Set **Read** permission for the following resources: - **Balance** and **Balance Transactions** -- for revenue analysis - **Charges** -- for payment success/failure tracking - **Customers** -- for customer context - **Invoices** -- for billing history - **Subscriptions** -- for MRR and churn analysis 5. Set **None** for all other resources. 6. Click **Create key** and copy the key (starts with `rk_live_` or `rk_test_`). While OpsTower also accepts standard secret keys (`sk_live_`, `sk_test_`), restricted keys are strongly recommended because they limit the blast radius if the key is ever compromised. A restricted read-only key cannot create charges, modify subscriptions, or perform any write operations on your Stripe account. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **Stripe**. 3. Enter your **API Key**. 4. Click **Test Connection** to verify your credentials. 5. Click **Save** to create the connection. ## What Agents Can Do with Stripe Once connected and enabled on an agent, the agent can: - **Query subscriptions** -- list active, canceled, past-due, and trialing subscriptions with automatic MRR calculation, plan details, and billing periods - **Query revenue** -- analyze balance transactions for gross revenue, fees, and net income over any time range - **Query charges** -- review payment attempts including successful, failed, and refunded charges with failure reasons - **Query invoices** -- inspect invoices by status (paid, open, draft, void) with amounts due, paid, and outstanding All monetary amounts from Stripe are in the smallest currency unit (e.g., cents for USD). Agents automatically convert these to readable dollar amounts in their responses. ## Use Cases - **Daily founder report**: Include MRR, new subscriptions, churn, and failed payments alongside product analytics - **Revenue investigation**: "Why did MRR drop this week?" -- the agent queries canceled subscriptions and correlates with product data - **Payment health monitoring**: Track failed charge rates and identify customers with past-due subscriptions - **Invoice auditing**: Review outstanding invoices and billing trends ## Troubleshooting - **Authentication failed**: Verify your API key is correct. Restricted keys start with `rk_live_` (live mode) or `rk_test_` (test mode). - **Permission denied on resource**: If using a restricted key, ensure the relevant resource has **Read** permission. The error message from Stripe will indicate which permission is missing. - **No data returned**: If using a test mode key (`rk_test_`), only test mode data will be returned. Switch to a live mode key for production data. - **Rate limited**: Stripe allows 100 requests/second in live mode and 25 requests/second in test mode. OpsTower's periodic queries are well within these limits. --- # Supabase Connection > Connect your Supabase PostgreSQL database to OpsTower to give your agents read-only SQL query access for data lookups and analysis. > URL: https://docs.opstowerapp.com/connections/supabase/ The Supabase connection integrates your Supabase PostgreSQL database with OpsTower, giving agents the ability to run read-only SQL queries against your data. All queries are limited to SELECT statements and return a maximum of 100 rows per query. ## Prerequisites You need a Supabase account with an active project. Both free-tier and paid Supabase projects are supported. ## Credentials Required To set up a Supabase connection, you need two pieces of information: - **Project URL** -- the URL of your Supabase project - **Service Role Key** -- a privileged API key for server-side access ## How to Find Your Project URL 1. Log in to [supabase.com](https://supabase.com) and open your project. 2. Go to **Project Settings** in the sidebar (the gear icon). 3. Select **API** from the settings menu. 4. Copy the **Project URL** shown at the top of the page. It follows the format `https://abc123.supabase.co`. ## How to Find Your Service Role Key 1. In the same **Project Settings > API** page. 2. Scroll to the **Project API Keys** section. 3. Find the `service_role` key (not the `anon` key). 4. Click **Reveal** to display the full key and copy it. It is a JWT that starts with `eyJ`. **Important**: The service role key bypasses Row Level Security (RLS). OpsTower only runs read-only SELECT queries against your database, but you should treat this key as highly sensitive. Do not share it or expose it in client-side code. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **Supabase**. 3. Enter your **Project URL** and **Service Role Key**. 4. Click **Save** to create the connection. ## What Agents Can Do with Supabase Once connected and enabled on an agent, the agent can: - Execute read-only SQL queries (SELECT statements only) against your PostgreSQL database - List all tables in the database - Inspect table schemas and relationships to understand your data model All queries are validated as read-only before execution. Write operations (INSERT, UPDATE, DELETE, DROP, etc.) are rejected. ## Troubleshooting - **Authentication errors**: Verify that you are using the `service_role` key, not the `anon` key. The anon key has limited permissions that may not cover all tables. - **No data returned**: Confirm that your project URL is correct and that the database contains data in the tables you are querying. - **Connection refused**: Ensure your Supabase project is active and not paused. Free-tier projects may be paused after a period of inactivity -- reactivate them from the Supabase dashboard. - **Missing tables**: If you cannot see certain tables, verify that they exist in the `public` schema. Tables in other schemas may require explicit schema qualification in queries. --- # X (Twitter) Connection > Connect your X (Twitter) account to OpsTower so agents can analyze tweets, engagement metrics, and mentions. > URL: https://docs.opstowerapp.com/connections/x-twitter/ The X (Twitter) connection integrates your account with OpsTower via OAuth, giving agents the ability to pull recent tweets, analyze engagement metrics, and search for mentions. ## Prerequisites You need an X (Twitter) account with API access. The connection uses OAuth 2.0 with PKCE for secure authorization. ## Setting Up the Connection in OpsTower 1. In OpsTower, navigate to **Connections** in the sidebar. 2. Click **Add Connection** and select **X (Twitter)**. 3. Click **Connect with X** to start the OAuth flow. 4. Authorize OpsTower in the X consent screen. 5. You will be redirected back to OpsTower with the connection active. ## What Agents Can Do Once connected and enabled on an agent, the agent can: - **List recent tweets** -- pull your recent posts with engagement data (likes, retweets, replies, impressions) - **Get tweet metrics** -- retrieve detailed metrics for specific tweet IDs - **Search mentions** -- find tweets mentioning your account or specific keywords ## Use Cases - **Social attribution**: Correlate a traffic spike in analytics with a high-engagement tweet - **Content performance**: Compare engagement across tweet types to understand what drives business outcomes - **Brand monitoring**: Track mentions and sentiment around your product --- # Zendesk Connection > Connect Zendesk to OpsTower to give your agents access to support tickets, CSAT ratings, help center articles, and performance metrics. > URL: https://docs.opstowerapp.com/connections/zendesk/ The Zendesk connection integrates your Zendesk instance with OpsTower, giving agents the ability to search tickets using Zendesk Query Language (ZQL), view ticket details with full conversation history, analyze CSAT ratings, browse help center articles, and review performance metrics like first reply time and resolution time. ## Prerequisites You need a Zendesk account with admin access to create an OAuth client. Unlike most OpsTower integrations, Zendesk requires you to register an OAuth client on your own Zendesk admin panel first. ### Creating the OAuth Client 1. Go to your Zendesk Admin Center (`your-subdomain.zendesk.com`). 2. Navigate to **Apps and integrations** > **APIs** > **OAuth clients**. 3. Click **Add OAuth client**. 4. Set the Client Name to "OpsTower". 5. Add a Redirect URL: `https://app.opstowerapp.com/api/oauth/callback` 6. Click **Save** and copy the **Client Identifier** and **Client Secret**. ## Setup in OpsTower 1. Go to **Connections** > **Customer Support** > **Add Connection**. 2. Select **Zendesk**. 3. Enter your **Zendesk subdomain** (e.g., `mycompany` if your URL is `mycompany.zendesk.com`). 4. Enter the **OAuth Client Identifier** and **Client Secret** from the prerequisite step. 5. Click **Connect to Zendesk**. 6. A popup opens to Zendesk's authorization page. Sign in and grant access. 7. Optionally add **Support Instructions** to guide how agents search and analyze your tickets. ## What Agents Can Do Once connected, agents have access to eight tools: - **Search Tickets** -- search using Zendesk Query Language (ZQL) with status, priority, tags, assignee, date, and more - **Get Ticket** -- view full ticket details including conversation history (comments) - **Get Ticket Metrics** -- first reply time, resolution time, wait times, reopens (single ticket or bulk summary) - **Query CSAT** -- customer satisfaction ratings with score and date filtering, plus CSAT percentage calculation - **Search Users** -- find requesters and agents by name, email, or role - **List Organizations** -- browse or search customer organizations - **Search Articles** -- search help center knowledge base articles - **List Views** -- see saved ticket filters with optional ticket counts ## ZQL Examples Agents use Zendesk Query Language (ZQL) to search tickets. Common patterns: - `status:open priority:urgent` -- urgent open tickets - `tags:billing status:pending` -- pending billing tickets - `requester:john@example.com` -- tickets from a specific user - `created>2026-04-01 group:"Tier 2 Support"` -- recent escalations - `assignee:me status Focus on billing tickets. Group 'Tier 2 Support' handles escalations. Tag 'vip' marks high-priority customers. These are injected into the agent's system prompt as preferences. ## Use Cases - "Show me all open urgent tickets from the last 7 days" - "What's our average first reply time this month?" - "What's our CSAT score? Show me recent bad ratings with comments" - "Find tickets from user john@example.com" - "Search our help center for articles about password reset" - "Which support views have the most tickets right now?" - "Show me ticket #12345 with all its comments" - "What organizations have the most open tickets?" --- # Key Concepts > Understand the core building blocks of OpsTower — agents, connections, reports, knowledge, AI models, and pricing tiers. > URL: https://docs.opstowerapp.com/getting-started/concepts/ This page covers the foundational concepts behind OpsTower. Understanding these building blocks will help you get the most out of the platform. ## Organizations Organizations are the top-level unit in OpsTower. Every resource -- agents, connections, reports, knowledge files -- belongs to an organization. Each organization has its own billing plan and team members. A single user can own multiple organizations and be a member of others. This is useful for consultants, freelancers, or anyone managing operations for multiple teams or clients. When you sign up, OpsTower creates a default organization for you. You can create additional organizations from the sidebar switcher and switch between them at any time. Each organization is completely isolated -- resources in one organization are never visible in another. ## Agents Agents are the core of OpsTower. Each agent is an autonomous assistant that connects to your data sources, answers questions, and performs investigations on your behalf. OpsTower offers two agent types, each specialized for a different operational need: ### Debugger Debugger agents are built for investigating errors and tracing issues across your stack. They can query logs, search through code repositories, and run database queries to piece together what went wrong and why. Typical use cases for Debugger agents: - Investigating production errors by correlating log entries with recent code changes. - Tracing a bug from a user-facing symptom through application logs to the root cause. - Querying database records to verify data integrity when an issue is reported. ### Analyst Analyst agents are built for analytics and trend analysis. They monitor your product metrics, detect anomalies, and surface changes that matter. Typical use cases for Analyst agents: - Tracking key product metrics like sign-ups, conversions, or retention over time. - Detecting sudden spikes or drops in user activity. - Generating periodic summaries comparing current performance against previous periods. ### Agent Configuration Each agent can be customized with: - **Multiple connections** -- enable any combination of your connected data sources. - **A specific AI model** -- override the global default model for this agent. - **Knowledge items** -- attach custom context to help the agent understand your systems. ## Connections Connections are integrations between OpsTower and your external services. They allow agents to read data from your analytics platforms, log providers, databases, and code repositories. Connections fall into four categories: ### Analytics Integrate with product analytics platforms to give Analyst agents access to event data, user behavior, and product metrics. | Service | Description | | --------- | --------------------------------------------------------- | | PostHog | Open-source product analytics | | Amplitude | Product analytics and event tracking | | GA4 | Google Analytics 4 | | Mixpanel | Event analytics with funnels, retention, and segmentation | ### Logs Connect log aggregation services so Debugger agents can search and analyze your application logs. | Service | Description | | -------------- | --------------------------------- | | Axiom | Log management and observability | | Cloudflare | Cloudflare Workers and CDN logs | | Google Cloud | Google Cloud Logging | | AWS CloudWatch | AWS monitoring and log management | ### Databases Grant agents read access to your databases for data verification and investigation queries. | Service | Description | | ----------- | ------------------------------------------------- | | ClickHouse | Columnar analytics database for real-time queries | | D1 | Cloudflare D1 serverless SQL database | | Supabase | Open-source Firebase alternative (PostgreSQL) | | Generic SQL | Any SQL database via connection string | | DynamoDB | AWS managed NoSQL database | | Firestore | Google Cloud NoSQL document database | ### Code Connect your code repositories so agents can search through source code, review recent changes, and correlate code modifications with production issues. | Service | Description | | ------- | ------------------------------------------- | | GitHub | Source code repositories and commit history | ## Reports Reports are automated analytics summaries generated by OpsTower. They are designed to keep you informed about your product's performance without requiring manual analysis. Each report includes: - **Key metrics** -- the numbers that matter most for your product. - **Period-over-period comparisons** -- how current values compare to the previous period. - **Anomaly detection** -- automatic identification of unusual patterns or sudden changes. - **AI-generated insights** -- plain-language explanations of what the data means and what might need attention. Reports can be **scheduled to run daily** and delivered via email, so your team starts each day with a clear picture of how things are going. Reports are tied to analytics connections (PostHog, Amplitude, GA4, Mixpanel). You can create multiple reports with different configurations and delivery schedules. ## Knowledge Knowledge allows you to provide agents with custom context about your systems, products, and processes. This helps agents give more relevant and accurate responses. There are three types of knowledge: ### Free-Form Text Write plain text descriptions directly in the OpsTower interface. Use this for quick context like: - Descriptions of your product architecture. - Team conventions and naming standards. - Known issues or ongoing incidents. ### Uploaded Files Upload documents in PDF, TXT, or Markdown format. This is useful for: - Technical design documents. - Runbooks and standard operating procedures. - Architecture diagrams and system documentation. ### Attached Reports Link an existing OpsTower report as a knowledge source. This gives agents access to your latest analytics data as background context when answering questions, combining real-time data access with historical trend awareness. ## AI Models OpsTower supports multiple AI model providers, giving you flexibility in choosing the right model for your needs. ### Supported Providers - **Anthropic** -- Claude model family. - **OpenAI** -- GPT model family. - **Google** -- Gemini model family. ### Model Configuration You can configure AI models at two levels: - **Global default** -- set a default model in your account settings that applies to all agents unless overridden. - **Per-agent override** -- assign a specific model to an individual agent, useful when different tasks benefit from different model strengths. ## Tiers OpsTower offers three pricing tiers to match teams of different sizes and needs. ### Explore (Free) The free tier is designed for individuals and small teams getting started with operational agents. It includes access to core features with usage limits on the number of agents, connections, and interactions. ### Operate (Pro) The Pro tier is built for growing teams that need more capacity. It raises the limits on agents, connections, and report scheduling, and unlocks additional configuration options. ### Scale (Business) The Business tier is designed for larger teams with advanced requirements. It includes the highest usage limits, priority support, and additional administrative controls for team management. --- ## Next Steps - Follow the [Quickstart](/getting-started/quickstart/) guide to set up your first agent. - Browse the [Connections](/connections/overview/) documentation to see all available integrations. - Learn how to configure [Reports](/reports/overview/) for automated analytics delivery. --- # Quickstart > Get up and running with OpsTower in minutes — sign up, connect a data source, create an agent, and start asking questions. > URL: https://docs.opstowerapp.com/getting-started/quickstart/ This guide walks you through setting up OpsTower from scratch. By the end, you will have a working agent connected to one of your data sources, ready to answer questions about your systems. ## 1. Sign Up for an Account OpsTower uses Clerk-based authentication. You can sign up with your email address or through a supported SSO provider. 1. Go to [opstowerapp.com](https://opstowerapp.com) and click **Sign Up**. 2. Create your account using email or a social login provider. 3. Once signed in, you will land on the OpsTower dashboard. A free tier (Explore plan) is available, so you can start using OpsTower without entering any payment information. ## 2. Connect Your First Data Source Agents need data sources to work with. Start by connecting at least one service. 1. Navigate to **Connections** in the sidebar. 2. Click **Add Connection** and choose a service to integrate. Good starting points include: - **PostHog**, **Amplitude**, or **Mixpanel** for product analytics - **Sentry** for error tracking - **Stripe** for payment and revenue analytics - **Axiom** or **Cloudflare** for application logs - **GitHub** for code repository access - **Linear** for ticketing and automated issue creation - **ClickHouse**, **MongoDB**, **Supabase**, or **D1** for database access 3. Follow the on-screen instructions to authorize the connection. Each service has its own authentication flow -- typically an API key or OAuth grant. 4. Once connected, the service will appear in your Connections list with a green status indicator. You can always add more connections later. Agents can use multiple data sources simultaneously. ## 3. Create Your First Agent With a data source connected, you can now create an agent. 1. Navigate to **Agents** in the sidebar. 2. Click **Create Agent**. 3. Choose an agent type: - **Debugger** -- best for investigating errors, tracing issues across logs, code, and databases. - **Analyst** -- best for analyzing product analytics, tracking metrics, and detecting trends. 4. Give your agent a name and an optional description. 5. Select an AI model or leave the default (the global default model will be used). 6. Click **Create**. ## 4. Enable Connections on Your Agent Your agent needs access to one or more of your connected data sources. 1. Open your newly created agent. 2. Go to the **Connections** tab within the agent settings. 3. Toggle on the connections you want the agent to use. For example, enable PostHog if you want the agent to analyze your analytics data, or enable GitHub and Axiom if you want it to debug issues across code and logs. 4. Save your changes. The agent can now query data from any enabled connection during conversations. ## 5. Start Chatting You are ready to interact with your agent. 1. Open your agent and navigate to the **Chat** view. 2. Ask a question related to your connected data. For example: - With an analytics connection: "What were my top events last week?" or "Show me the trend for sign-ups over the past 30 days." - With a logs connection: "Are there any recurring errors in the last 24 hours?" - With a code connection: "What changed in the authentication module recently?" 3. The agent will query the relevant data sources and provide an answer with supporting details. You can ask follow-up questions to drill deeper into any response. ## 6. (Optional) Set Up Scheduled Reports If you connected an analytics platform, you can configure automated reports that run on a schedule. 1. Navigate to **Reports** in the sidebar. 2. Click **Create Report** and select the analytics connection to use. 3. Configure the report parameters -- metrics to track, comparison periods, and anomaly detection sensitivity. 4. Enable **daily scheduling** and provide an email address for delivery. 5. Save the report. Reports run automatically and deliver a summary with key metrics, period-over-period comparisons, detected anomalies, and AI-generated insights directly to your inbox. For Systems Operations reports, you can also enable **auto-ticketing** -- when the report agent finds issues, it automatically creates Linear tickets with severity, classification, and evidence. See [Reports Overview](/reports/overview/) for details. ## Next Steps - Read the [Key Concepts](/getting-started/concepts/) page to understand how agents, connections, reports, and knowledge work together. - Explore the [Connections](/connections/overview/) documentation to integrate additional data sources. - Learn how to add [Knowledge](/knowledge/overview/) to give your agents custom context about your systems. --- # Supported Integrations > Quick reference of all integrations available in OpsTower, including authentication methods and required credentials. > URL: https://docs.opstowerapp.com/reference/supported-integrations/ OpsTower supports 34 integrations across twelve categories: analytics, error tracking, payments, logs, databases, ticketing, code, social, advertising, app stores, customer support, and external APIs. This page provides a quick reference for each integration's authentication method and required credentials. ## Integration Reference | Integration | Category | Auth Method | Key Credentials | | -------------------- | -------------- | ------------------- | ---------------------------------------------------- | | PostHog | Analytics | API Key | API key (`phx_`), Project ID | | Amplitude | Analytics | OAuth 2.0 | Automatic via OAuth | | Google Analytics 4 | Analytics | Service Account | JSON key file, Property ID | | Mixpanel | Analytics | Service Account | Service Account Username, Secret, Project ID | | Sentry | Error Tracking | Auth Token | Internal Integration token, Organization slug | | Stripe | Payments | API Key | Restricted API key (`rk_live_`) | | Axiom | Logs | API Token | Token (`xaat-` / `xapt-`), Dataset | | Cloudflare Logging | Logs | API Token | API token, Account ID | | Google Cloud Logging | Logs | Service Account | JSON key file, Project ID | | AWS CloudWatch | Logs | IAM Credentials | Access Key, Secret Key, Region | | MongoDB | Database | Connection String | Connection string (`mongodb://` or `mongodb+srv://`) | | ClickHouse | Database | Username / Password | URL, Username, Password, Database | | Cloudflare D1 | Database | API Token | API token, Account ID, Database ID | | Supabase | Database | JWT | Project URL, Service Role Key | | Generic SQL | Database | Connection String | Connection string (`postgres://` or `mysql://`) | | AWS DynamoDB | Database | IAM Credentials | Access Key, Secret Key, Region | | Google Firestore | Database | Service Account | JSON key file, Project ID | | Linear | Ticketing | API Key | Personal API key (`lin_api_`) | | GitHub | Code | PAT | Personal Access Token | | Paddle | Payments | API Key | API key (`pdl_live_` or `pdl_sdbx_`), Environment | | Chargebee | Payments | API Key | Site subdomain, Read-only API key | | Braintree | Payments | API Key | Merchant ID, Public Key, Private Key, Environment | | Jira Cloud | Ticketing | OAuth 2.0 (PKCE) | Automatic via OAuth, Cloud ID | | Bitbucket Cloud | Code | OAuth 2.0 (PKCE) | Automatic via OAuth, Workspace slug | | GitLab | Code | OAuth 2.0 (PKCE) | Automatic via OAuth, Username | | X (Twitter) | Social | OAuth 2.0 (PKCE) | Automatic via OAuth | | LinkedIn | Social | OAuth 2.0 | Automatic via OAuth | | Facebook & Instagram | Social | OAuth 2.0 | Automatic via OAuth (Page Access Token) | | Meta Ads | Advertising | OAuth 2.0 | Automatic via OAuth, Ad Account ID | | Google Ads | Advertising | OAuth 2.0 | Automatic via OAuth, Customer ID | | App Store Connect | App Store | API Key (JWT) | Issuer ID, Key ID, Private Key (.p8) | | Intercom | Support | OAuth 2.0 | Automatic via OAuth | | Zendesk | Support | OAuth 2.0 (PKCE) | Subdomain, OAuth Client Identifier, Client Secret | | External API | External API | Flexible | Base URL + Bearer / API Key / Basic Auth / Query Param / None | ## Credential Security All credentials are encrypted at rest using AES-GCM. Credentials are decrypted only at the time of use and are never exposed in logs, API responses, or the user interface after initial entry. ## Category Overview ### Analytics Analytics integrations connect OpsTower to your product analytics platforms. They power both scheduled reports and real-time agent queries during chat sessions. ### Logs Log integrations give agents access to application and infrastructure logs. Agents can search, filter, and analyze log data to help with debugging and incident investigation. ### Databases Database integrations allow agents to query your data stores directly. Agents can run read-only queries to retrieve data relevant to your questions. ### Error Tracking Error tracking integrations give agents access to grouped error data with stack traces, frequency trends, and project-level stats. Agents can surface overnight error spikes and correlate them with other signals. ### Payments Payment integrations connect agents to your revenue and subscription data. Agents can query subscriptions, charges, invoices, and balance transactions to include financial metrics in daily reports. ### Ticketing Ticketing integrations let agents search, view, and create issues in your project management tools. They enable automated ticket creation from systems operations reports, so issues discovered overnight are tracked before your team starts the day. ### Code Code integrations provide agents with access to your source code repositories. Agents can browse files, search code, and review commit history to correlate code changes with observed issues. ### Social Social integrations connect agents to your social media accounts for engagement metrics, post performance, and audience insights. Agents can correlate social activity with product analytics to attribute traffic spikes and measure content impact. ### Advertising Advertising integrations connect agents to your ad platforms for campaign performance, spend analytics, and audience breakdowns. Agents can correlate paid acquisition with product metrics to calculate true CAC and ROAS. ### App Stores App store integrations connect agents to mobile app distribution platforms. Agents can query app reviews, ratings, and metadata to surface user sentiment, track review trends, and correlate app store feedback with product analytics. ### Customer Support Customer support integrations give agents access to support tickets, conversations, CSAT ratings, help center articles, and performance metrics. Agents can correlate customer issues with product analytics and operational signals to surface patterns and drive faster resolution. ### External APIs External API connections let you integrate any REST API that OpsTower does not have a dedicated integration for. Provide a base URL and authentication credentials, and agents can make HTTP requests to query data from any service -- internal microservices, third-party SaaS platforms, or partner data feeds. All requests include SSRF protection and header sanitization. --- # Generating and Viewing Reports > Learn how to generate on-demand reports, view completed reports, download them, and chat with an AI agent about report findings. > URL: https://docs.opstowerapp.com/reports/generating/ OpsTower lets you generate analytics reports on demand from your connected analytics platforms. This guide covers how to create, view, download, and discuss reports. ## Generating a Report 1. Navigate to the analytics connection you want to report on (PostHog, Amplitude, or Mixpanel). 2. Go to the connection's **Reports** page. 3. Click **Generate Report**. The system will create a new report and begin processing it. Only one report per day per connection is allowed -- if you have already generated a report today for a given connection, you will need to wait until the next day. ## Report Statuses After you trigger a report, it moves through the following statuses: | Status | Description | | ------------- | ---------------------------------------------------------------------------------------- | | **Pending** | The report has been created and is queued for processing. | | **Running** | The AI agent is actively querying your analytics platform and assembling the report. | | **Completed** | The report has been generated successfully and is ready to view. | | **Failed** | Something went wrong during generation. Check your connection credentials and try again. | ## Viewing a Report 1. Go to the connection's **Reports** page. 2. Find the completed report in the list. 3. Click the report to open it in the report viewer. Reports render as formatted HTML within the viewer, displaying metrics, comparisons, anomalies, and the AI-generated summary. ## Downloading a Report 1. Open a completed report in the viewer. 2. Click the **Download** button in the report viewer toolbar. 3. The report is saved as an HTML file to your local machine. The downloaded file is self-contained and can be opened in any web browser or shared as an email attachment. ## Chatting About a Report You can discuss a report's findings with an AI agent directly from the viewer: 1. Open a completed report in the viewer. 2. Click **Chat about this report**. 3. OpsTower creates a temporary **Analyst agent** with the report attached as context. 4. Ask questions about the data, request deeper analysis, or explore specific metrics in conversation. The temporary Analyst agent is automatically cleaned up after 24 hours. This keeps your workspace tidy while giving you a window to explore the report interactively. ## Auto-Ticketing in Systems Operations Reports Systems Operations reports support automatic ticket creation during report generation. When enabled, the report agent creates tickets in your ticketing system (e.g., Linear) for issues it discovers. To set this up: 1. Add a **tickets connection** (e.g., Linear) to the report's data sources. 2. Go to the report's **Ticketing** tab and enable auto-ticketing. 3. Choose whether to create tickets for all issues or only code-related bugs. When the report runs, any issues matching your configured scope will have tickets created automatically. The tickets appear as links in the report's Issues Found section. See [Reports Overview](/reports/overview/#auto-ticketing-systems-operations-reports) for full details. --- # Reports Overview > Understand how OpsTower reports work -- automated analytics summaries generated by AI agents from your connected analytics platforms. > URL: https://docs.opstowerapp.com/reports/overview/ Reports are automated analytics summaries generated by AI agents that query your connected analytics platforms. OpsTower supports report generation from PostHog, Amplitude, and Mixpanel connections, producing structured data and formatted output that you can view, download, and discuss with an AI agent. ## What a Report Contains Each report includes several sections that together provide a comprehensive snapshot of your product analytics. ### Metrics Reports cover the following key metrics for the reporting period: - Unique users - Total sessions - New users - Returning users - Average session duration - Top pages ### Comparisons Every metric includes period-over-period comparisons with percentage changes: - **Today vs. yesterday** -- shows daily movement - **Today vs. 7 days ago** -- shows weekly trends These comparisons help you quickly identify whether metrics are trending up or down relative to recent baselines. ### Anomaly Detection Metrics that changed by more than 30% compared to the previous period are automatically flagged as anomalies. This draws attention to significant shifts that may require investigation, whether they represent unexpected growth, sudden drops, or irregular patterns. ### AI Summary Each report includes a natural language summary written by the AI agent. The summary analyzes the data holistically and highlights: - Key trends across metrics - Areas of concern (e.g., declining engagement, traffic drops) - Notable insights (e.g., a spike in new users correlating with a campaign launch) ## How Reports Are Stored Reports are stored in two formats: - **JSON** -- structured data containing all metrics, comparisons, and anomaly flags, suitable for programmatic access - **HTML** -- a formatted version designed for viewing in the browser and for email delivery Report files are stored in **Cloudflare R2** (object storage), and report metadata (status, timestamps, connection references) is stored in **Cloudflare D1** (database). ## Auto-Ticketing (Systems Operations Reports) Systems Operations reports can automatically create tickets in your ticketing system (e.g., Linear) for issues discovered during the report run. This means overnight errors and bugs are already tracked in your project management tool before your team starts the day. ### How to Enable Auto-Ticketing 1. When creating or editing a Systems Operations report, add a **tickets connection** (e.g., Linear) to the report's data sources. 2. Go to the **Ticketing** tab in the report settings. 3. Toggle **Create tickets for found issues** on. 4. Choose a scope: - **All found issues** -- a ticket is created for every issue the agent discovers - **Code-related issues only** -- tickets are created only for issues classified as CODE_BUG (requires a source code connection for best results) 5. Save the settings. ### What Happens During a Report Run When the report agent runs with auto-ticketing enabled: - The agent investigates logs, errors, databases, and (optionally) source code as usual. - For each issue that matches the configured scope, the agent creates a ticket with the issue title, classification, severity, relevant evidence, and a recommended action. - The agent uses your **ticketing instructions** (configured on the Linear connection) to follow your team's conventions for teams, labels, and priority. - Created tickets are linked directly from the report's Issues Found section, so you can jump from the report to the ticket. ### Prerequisites - A **tickets connection** (e.g., Linear) must be in the report's data sources. - For the "code-related only" scope, adding a **source code connection** (e.g., GitHub) improves accuracy, though the agent can still classify issues without it. ## Tier Limits The number of reports you can generate per month depends on your plan: | Plan | Reports per Month | | ---------------- | ----------------- | | Explore (Free) | 5 | | Operate (Pro) | 31 | | Scale (Business) | Unlimited | Usage resets monthly (UTC). See [Plans and Limits](/settings/plans-and-limits/) for full details on all plan features. --- # Scheduling Reports > Set up automated report generation on a daily schedule with email delivery to your team. > URL: https://docs.opstowerapp.com/reports/scheduling/ Scheduled reports let you automate daily analytics report generation and deliver the results directly to your team's inboxes. This feature requires the **Operate (Pro)** tier or higher. ## Setting Up a Schedule 1. Navigate to the analytics connection you want to schedule (PostHog, Amplitude, or Mixpanel). 2. Open the connection's **Settings**. 3. Find the **Schedule** section. 4. Toggle **Enable scheduled reports** to on. 5. Configure the schedule: - **Hour** -- select the hour of day (0--23) when the report should be generated. - **Timezone** -- select your timezone. This is auto-detected from your browser by default. Over 30 timezones are available. 6. Add **email recipients** -- enter the email addresses of people who should receive the report. You can add up to 20 recipients per connection. Each address is validated for proper format before saving. 7. Click **Save**. ## How Scheduling Works OpsTower runs an hourly cron job that checks all scheduled reports. When the current hour in your configured timezone matches the hour you selected, a report is automatically generated for that connection. For example, if you set the hour to `9` and the timezone to `America/New_York`, the report will generate every day at 9:00 AM Eastern Time. ## Email Delivery Once a scheduled report completes, it is emailed to all configured recipients. Email delivery is powered by **Resend**. Recipients receive a formatted HTML email containing the full report -- metrics, comparisons, anomalies, and the AI summary -- directly in their inbox. ### Email Recipient Limits The number of email recipients you can configure depends on your plan: | Plan | Email Recipients | | ---------------- | ---------------- | | Explore (Free) | 3 | | Operate (Pro) | Unlimited | | Scale (Business) | Unlimited | ## Managing a Schedule ### Disabling a Schedule You can disable scheduled reports at any time by toggling **Enable scheduled reports** to off in the connection settings. Your configuration (hour, timezone, recipients) is preserved, so you can re-enable it later without reconfiguring. ### Changing the Schedule To change the generation time, update the **Hour** or **Timezone** fields and save. The new schedule takes effect on the next hourly cron cycle. ### Updating Recipients Add or remove email addresses in the recipients list and save. Changes take effect immediately for the next scheduled report. ## Requirements - **Plan**: Operate (Pro) or Scale (Business). Scheduled reports are not available on the Explore (Free) plan. - **Connection**: A valid, active analytics connection (PostHog or Amplitude) with working credentials. --- # AI Models > Configure which AI models your agents use -- OpsTower supports models from Anthropic, OpenAI, and Google across multiple capability tiers. > URL: https://docs.opstowerapp.com/settings/ai-models/ OpsTower supports a range of AI models from multiple providers. You can configure default models for different agent types and override them on a per-agent basis. ## Available Models ### Anthropic | Model | Capability | Tier | | ---------------- | ------------ | ------------------------- | | Claude Opus 4 | Most capable | Premium+ | | Claude Sonnet 4 | Balanced | Standard (system default) | | Claude Haiku 4.5 | Fastest | Standard | ### OpenAI | Model | Capability | Tier | | ---------- | ------------ | -------- | | GPT-5.4 | Most capable | Premium | | GPT-5 Mini | Fast | Standard | ### Google | Model | Capability | Tier | | --------------------- | ------------ | -------- | | Gemini 3.1 Pro | Most capable | Premium | | Gemini 3 Flash | Balanced | Standard | | Gemini 3.1 Flash Lite | Lightweight | Standard | ## Model Tiers Models are grouped into three tiers that correspond to plan levels: - **Standard** -- available on all plans (Explore, Operate, Scale) - **Premium** -- available on Operate (Pro) and Scale (Business) plans - **Premium+** -- available on Scale (Business) only ## Web Search and Fetch Tools The tools available for web access vary by provider: | Provider | Web Tools | | --------- | -------------------------- | | Anthropic | Web Search, Web Fetch | | Google | Google Search, URL Context | | OpenAI | Web Search | ## Setting Default Models You can configure a default model for each agent scope on the **Settings** page. The available scopes are: - **Debugger agents** -- the default model used by all Debugger agents - **Analyst agents** -- the default model used by all Analyst agents - **PostHog reports** -- the model used when generating reports from PostHog connections - **Amplitude reports** -- the model used when generating reports from Amplitude connections - **Mixpanel reports** -- the model used when generating reports from Mixpanel connections To set a default: 1. Navigate to the **Settings** page. 2. Find the model scope you want to configure. 3. Select a model from the dropdown. 4. Save your changes. ## Per-Agent Override You can override the default model for any individual agent: 1. Open the agent you want to configure. 2. Go to the agent's **General** settings. 3. Select a different model from the model dropdown. 4. Save. This agent will now use the selected model regardless of the scope default. ## Model Resolution Order When OpsTower determines which model to use for an agent, it follows this resolution order: 1. **Per-agent override** -- if a model is explicitly set on the agent, it is used. 2. **Scope default** -- if no per-agent override exists, the default for the agent's scope (e.g., Debugger, Analyst) is used. 3. **System default** -- if no scope default is configured, the system default (**Claude Sonnet 4**) is used. --- # Plans and Limits > Compare OpsTower plans -- Explore, Operate, and Scale -- and understand the limits for agents, connections, reports, chat, and models. > URL: https://docs.opstowerapp.com/settings/plans-and-limits/ OpsTower offers three plans designed to scale with your needs, from individual exploration to full team operations. ## Plan Comparison | Feature | Explore (Free) | Operate (Pro) | Scale (Business) | | -------------------------- | -------------- | ------------------ | ----------------------------- | | Agents | 2 | 5 | Unlimited | | Connections | 4 | 15 | Unlimited | | Reports per month | 5 | 31 | Unlimited | | Chat messages per month | 100 | Unlimited | Unlimited | | Model tiers | Standard only | Standard + Premium | Standard + Premium + Premium+ | | Knowledge files per agent | 2 | 10 | 20 | | Custom knowledge size | 10 KB | 50 KB | Unlimited | | Email recipients (reports) | 3 | Unlimited | Unlimited | | Scheduled reports | No | Yes (fixed hour) | Yes (custom cron) | | Priority support | No | No | Yes | ## Plan Details ### Explore (Free) The Explore plan is designed for getting started with OpsTower. It includes enough capacity to set up a couple of agents, connect a few data sources, and generate a handful of reports each month. Chat usage is capped at 100 messages per month. Only standard-tier models are available. ### Operate (Pro) The Operate plan is built for regular use. It raises limits across the board -- more agents, more connections, and daily report generation. Chat messages are unlimited. You gain access to premium-tier models and can schedule automated daily reports at a fixed hour with email delivery to your team. ### Scale (Business) The Scale plan removes all caps on agents, connections, reports, and chat. It unlocks premium+ models (including Claude Opus 4), allows custom cron schedules for reports, and includes priority support. ## Usage Tracking All usage counters (reports, chat messages) reset monthly on a UTC basis. You can view your current usage at any time through the account settings in the app. ## Upgrading To upgrade your plan, visit the account settings page in OpsTower. Plan changes take effect immediately, and your new limits are available right away. --- # Organizations & Teams > Create multiple organizations, invite team members, and switch between them in OpsTower. > URL: https://docs.opstowerapp.com/settings/team-invitations/ OpsTower uses **organizations** to group resources together. Each organization has its own agents, connections, reports, knowledge files, billing plan, and team members. A single user can own multiple organizations and be a member of others. ## How Organizations Work When you first sign up, OpsTower creates a default organization for you. All your agents, connections, and reports belong to this organization. You can create additional organizations for different teams, projects, or clients. Each organization is completely isolated -- resources in one organization are not visible in another. ## Creating Organizations To create a new organization: 1. Click the **organization switcher** at the top of the sidebar. 2. Click **Create New Organization** at the bottom of the dropdown. 3. Enter a name for the organization and click **Create Organization**. The new organization starts on the free tier with no resources. You'll be automatically switched to it after creation. There is no limit on how many organizations you can create. ## Switching Between Organizations The **organization switcher** is always visible at the top of the sidebar. Click it to see all organizations you have access to (owned and invited), then select the one you want to work with. - A crown icon indicates organizations you own. - A role badge (e.g., "viewer") appears for organizations you've been invited to. - A checkmark shows which organization is currently active. Your selected organization is remembered across sessions. ## Renaming an Organization To rename an organization you own: 1. Go to **Settings** in the sidebar. 2. Select the **Organization** tab. 3. Edit the organization name and click **Save**. ## Inviting Team Members To invite someone to your organization: 1. Go to **Settings** in the sidebar. 2. Select the **Organization** tab. 3. Enter the email address of the person you want to invite. 4. Click **Invite**. An invitation email is sent with a link to accept. The invitation expires after **7 days**. If the invitee doesn't have an OpsTower account yet, they'll be prompted to sign up when they click the invitation link. After signing up, the invitation is accepted automatically. :::note The invitation can only be accepted by a user whose email address matches the invited email. ::: ## Accepting an Invitation When you receive an invitation email: 1. Click the **Accept Invitation** link in the email. 2. If you're not signed in, you'll be prompted to sign in or create an account. 3. Once signed in, the invitation is accepted and you'll see the organization in your sidebar switcher. ## Roles and Permissions Currently, invited members receive the **viewer** role. Here's what each role can do: | Capability | Owner | Viewer | |---|---|---| | View agents, connections, reports | Yes | Yes | | Chat with agents | Yes | Yes | | Run investigations | Yes | Yes | | Chat with report results | Yes | Yes | | Pin items to the sidebar | Yes | Yes | | Create or edit agents | Yes | No | | Create or edit connections | Yes | No | | Create or modify reports | Yes | No | | Trigger report runs | Yes | No | | Manage schedules | Yes | No | | Upload knowledge files | Yes | No | | Manage billing | Yes | No | | Invite or remove team members | Yes | No | | Rename the organization | Yes | No | When viewing an organization as a viewer, create and settings buttons are disabled with a tooltip indicating view-only access. :::tip Each team member gets their own private chat sessions with agents. You won't see each other's chat history. ::: ## Managing Invitations and Members From **Settings > Organization**, the organization owner can: - **View pending invitations** -- See all outstanding invitations with their expiry dates. - **Revoke an invitation** -- Cancel a pending invitation before it's accepted. - **View organization members** -- See all current members with their roles and join dates. - **Remove a member** -- Revoke a member's access immediately. They'll be switched back to their own organization on their next page load. ## Billing Per Organization Each organization has its own billing plan. When you create a new organization, it starts on the **free tier**. You can upgrade each organization independently. Usage limits (agents, connections, reports, chat messages) are tracked per organization. Team members share the organization's usage quota. ## Connection Security Invited viewers can see your connections and use them through agents and investigations, but they **cannot see connection credentials**. API keys, passwords, and tokens are never exposed to viewers -- they only see the connection label and type. ## Frequently Asked Questions **Can I invite someone as an editor?** Not yet. The editor role is planned for a future update. Currently all invited members are viewers. **Is there a limit on how many people I can invite?** There is no limit on invitations at this time. **Can I transfer ownership of an organization?** Not currently. Ownership transfer is planned for a future update. **Can I delete an organization?** Not currently. Organization deletion is planned for a future update. **What happens if I remove a team member?** They immediately lose access to your organization. Any of their in-progress chat sessions with your agents will stop working. Their own organizations and data are not affected. **Can a viewer see my billing information?** Viewers cannot access billing settings or subscription management.