Cloudlink Documentation

What is Cloudlink?#

Cloudlink Global is a cloud cost intelligence platform that helps engineering teams find, understand, and fix cloud cost problems automatically. Unlike traditional cost tools that show you aggregated spend, Cloudlink links every cost change to the specific deploy, resource, or configuration that caused it.

We connect to your cloud accounts read-only and continuously monitor for cost regressions, idle resources, and billing anomalies. When we find something, we alert your team via Slack or email with the exact cause, estimated monthly impact, and a recommended fix.

Our business model is simple: we charge 15% of what we save you. If we save you nothing, you pay nothing.

How the pricing works#

Cloudlink operates on a pure performance model. There are no subscriptions, no upfront fees, and no monthly minimums.

Here is exactly how it works:

• We connect to your cloud account and monitor continuously
• Every time we find and fix a cost problem, we log the saving
• At the end of each month, we calculate your total verified savings
• We invoice you for 15% of that total
• If your savings for the month are under $500, they roll over to the following month
• If we save you nothing, you owe us nothing

Example: If Cloudlink saves your team $20,000 in a month, your invoice is $3,000. You keep $17,000.

Quick start (5 minutes)#

System requirements#

Cloudlink is a hosted SaaS product — there is nothing to install or maintain. The only requirements are:

• An AWS, GCP, or Azure account with permission to deploy IAM roles or service accounts
• Access to the relevant cloud console to deploy the Cloudlink read-only role
• A modern browser (Chrome, Firefox, Safari, Edge)

For SDK usage, you will need Python 3.8+ or Node.js 16+.

Connecting AWS#

Prerequisites: AWS account with permission to deploy CloudFormation stacks.

Important: Cloudlink only ever has read access to your AWS account. We can never modify, create, or delete any resources without your explicit approval through the dashboard.

Services we access

• AWS Cost Explorer — cost and usage data
• CloudWatch — metrics and resource utilisation
• EC2 — instance inventory and state
• EBS — volume inventory and attachment status
• Lambda — function inventory and invocation metrics
• RDS — database instance inventory
• S3 — bucket inventory and public access settings

Connecting Azure#

Azure connection uses an Azure Active Directory service principal with read-only permissions.

# Create the service principal and note the output
az ad sp create-for-rbac \
  --name "CloudlinkReadOnly" \
  --role "Reader" \
  --scopes /subscriptions/<SUBSCRIPTION_ID>

az role assignment create \
  --assignee <SERVICE_PRINCIPAL_APP_ID> \
  --role "Cost Management Reader" \
  --scope /subscriptions/<SUBSCRIPTION_ID>

Connecting GCP#

GCP connection uses a service account with the Viewer and Billing Account Viewer roles.

gcloud iam service-accounts create cloudlink-readonly \
  --description="Cloudlink read-only access" \
  --display-name="Cloudlink Read Only"

# Viewer role for resource inventory
gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member="serviceAccount:cloudlink-readonly@<PROJECT_ID>.iam.gserviceaccount.com" \
  --role="roles/viewer"

# Billing viewer for cost data
gcloud billing accounts add-iam-policy-binding <BILLING_ACCOUNT_ID> \
  --member="serviceAccount:cloudlink-readonly@<PROJECT_ID>.iam.gserviceaccount.com" \
  --role="roles/billing.viewer"

gcloud iam service-accounts keys create cloudlink-key.json \
  --iam-account=cloudlink-readonly@<PROJECT_ID>.iam.gserviceaccount.com

Managing connections#

All connected cloud accounts are listed in Settings → Cloud Connections. From this page you can:

• View connection status and last successful sync time
• Manually trigger a re-scan for any account
• Rotate credentials for any connection
• Remove a cloud account connection
• Connect additional accounts (multi-account support for AWS Organisations)

Overview page#

The Overview page is the main landing page of your Cloudlink dashboard. It gives you an at-a-glance view of your cloud cost health across all connected accounts.

The overview page shows:

• Total savings this month — verified savings generated by Cloudlink actions and detections
• Active regressions — cost spikes that have been detected and are awaiting resolution
• Idle resources — resources with zero or near-zero utilisation that are still incurring charges
• Cost trend — your cloud spend over the last 30 days against your baseline

Reading the KPI cards#

The KPI cards at the top of each dashboard page show high-level metrics. Each card includes:

• Current value — the current period (month-to-date or trailing 30 days depending on the page)
• Delta indicator — the change versus the prior period, shown in green (improvement) or red (regression)
• Sparkline — a mini chart showing the trend over the last 7 days

Cost over time chart#

The cost over time chart shows your total cloud spend as a daily time series. The chart includes:

• Actual spend line — your real daily cloud spend
• Baseline band — the expected spend range based on your historical pattern
• Regression markers — vertical lines marking when a cost regression was detected
• Deploy markers — optional markers when a deployment was recorded via the webhook

You can filter the chart by service, region, or resource type using the controls above the chart.

Savings breakdown#

The Savings page breaks down your verified savings by category:

• AutoStop savings — from automatically stopping idle instances
• Idle resource savings — from resources that were flagged and decommissioned
• Regression prevention — from cost spikes that were detected and resolved
• Rightsizing — from instances that were downsized after utilisation analysis

Setting your date range#

Most dashboard pages have a date range picker in the top-right corner. You can select:

• Last 7 days, 30 days, or 90 days
• Current month (month-to-date)
• Custom date range

The date range affects all charts, tables, and KPI cards on the page. It does not affect ongoing monitoring or alert thresholds.

What is a regression?#

A cost regression is a statistically significant increase in cloud spend for a given service that exceeds your established baseline. Regressions are typically caused by:

• A code deploy that introduced an inefficiency (e.g. a Lambda function with an infinite retry loop)
• A configuration change that increased resource consumption (e.g. increasing instance count in an autoscaling group)
• An unexpected traffic spike that triggered unintended scaling
• A new resource being provisioned and left running

Cloudlink detects regressions by comparing your current spend rate against a rolling 30-day baseline for each individual service. A spike of more than 20% above baseline triggers an alert.

How detection works#

Cloudlink runs cost analysis every hour using data from AWS Cost Explorer and CloudWatch. The detection algorithm:

1. Fetches the current hour's spend per service
2. Computes a rolling 30-day baseline (median spend rate) for each service
3. Flags any service where current spend exceeds baseline × 1.20
4. Checks recent deploy events to attribute the regression to a specific commit or deploy
5. Calculates the projected monthly impact
6. Creates a regression record and sends alerts

Detection latency is typically under 2 hours from the time the regression begins.

Reading a regression alert#

Each regression alert includes:

• Service name — the AWS service or specific resource where the spike occurred
• Delta — the percentage increase over baseline (e.g. +140%)
• Monthly impact — projected cost increase per month if not resolved
• Deploy attribution — if a deploy event was found within 4 hours of the spike, it is shown here with the commit SHA and author
• Suggested action — a recommended fix generated by the AI analysis engine

Approving and rejecting fixes#

For each regression, Cloudlink may suggest an automated fix. You can:

• Approve — Cloudlink will apply the fix automatically (e.g. stop an idle instance, revert a Lambda memory setting)
• Reject — dismiss the suggestion without action
• Mark resolved — if your team has already manually fixed the regression
• Snooze — pause alerts for this regression for 24 hours

Note: Cloudlink never applies changes to your infrastructure without explicit approval. Approval is logged with a timestamp and the user who approved it.

Regression history#

The Regressions → History tab shows all past regressions and their resolution status. For each regression you can see:

• The service and timeframe of the regression
• Total cost impact (actual spend above baseline during the regression window)
• How it was resolved and by whom
• Whether the saving was credited to your monthly invoice

What we scan for#

Every scan evaluates resources across several waste categories:

• Idle resources — running resources with no meaningful activity
• Unattached resources — provisioned resources not attached to anything (e.g. unattached EBS volumes)
• Over-provisioned resources — instances consistently using far less CPU or memory than their type provides
• Stopped-but-not-terminated resources — EC2 instances that are stopped but still incurring EBS and Elastic IP charges
• Public S3 buckets — buckets with public access that may be incurring egress charges

EC2 and compute#

For EC2 instances, Cloudlink analyses:

• CPU utilisation — instances with average CPU below 5% for 7+ days are flagged as idle
• Network I/O — instances with near-zero network activity are flagged regardless of CPU
• Instance age — instances older than 90 days with no naming convention are flagged for review
• Rightsizing opportunities — instances consistently using less than 20% of their type's CPU/RAM ceiling

Cloudlink only recommends stopping or rightsizing — it will never terminate an instance without explicit approval.

EBS and storage#

EBS volumes incur charges regardless of whether they are attached to an instance. Cloudlink flags:

• Unattached volumes — volumes with state=available (not attached to any instance)
• Volumes attached to stopped instances — you're still paying for these
• Old snapshots — EBS snapshots older than 180 days that have no corresponding active volume

Lambda functions#

For Lambda functions, Cloudlink analyses:

• Zero invocations — functions with no invocations in 30+ days
• Memory over-provisioning — functions consistently using less than 30% of their allocated memory
• Throttling patterns — functions with high throttle rates that may indicate concurrency misconfigurations
• Cost regressions — sudden spikes in Lambda duration or invocation count

RDS and databases#

RDS instances are often one of the largest line items on a cloud bill. Cloudlink identifies:

• Idle databases — RDS instances with near-zero connections for 14+ days
• Stopped databases — RDS instances in stopped state (they resume billing after 7 days automatically)
• Single-AZ production databases — a reliability and cost flag (no HA surcharge, but potential incident risk)
• Oversized instances — databases using less than 10% of available CPU/memory

S3 buckets#

S3 costs are driven by storage size and egress. Cloudlink identifies:

• Buckets with no lifecycle policy — objects accumulate indefinitely with no automatic cleanup
• High-egress buckets — buckets generating significant cross-region or internet egress charges
• Publicly accessible buckets — potential security and cost issue if accessed externally
• Buckets with Intelligent-Tiering potential — large buckets with mixed access patterns that could save with S3 Intelligent-Tiering

AutoStopping#

AutoStopping automatically stops idle development and staging resources on a schedule or based on inactivity signals.

How it works:

1. You create an AutoStop rule targeting a resource or tag group (e.g. Environment=staging)
2. Cloudlink monitors the resources for inactivity signals (no SSH sessions, no HTTP traffic, CPU below threshold)
3. When the inactivity threshold is reached, Cloudlink stops the resources and logs the action
4. Resources restart instantly when traffic resumes or can be manually started from the dashboard

Important: AutoStopping is designed for non-production workloads only. Always exclude production resources from AutoStop rules by using environment tags.

How savings are calculated#

Cloudlink tracks two categories of verified savings:

1. Direct action savings

These are savings from actions Cloudlink took directly or that you approved through the dashboard:

• AutoStopping an idle dev/staging environment
• Deleting an unattached EBS volume
• Stopping an idle EC2 instance
• Fixing an over-provisioned Lambda function

Calculation: We record the resource cost before the action and subtract the cost after. The difference is your saving.

2. Regression prevention savings

These are savings from cost regressions that Cloudlink detected and your team resolved:

• A deploy that caused a 40% cost spike, which your team reverted after Cloudlink alerted them

Calculation: We compare actual spend against your 30-day rolling baseline for that service. Spend above baseline that was reduced after a Cloudlink alert counts as a prevented regression cost.

What we do NOT count

• General cloud cost reductions unrelated to Cloudlink actions or alerts
• Savings from resources you fixed before Cloudlink flagged them
• Normal seasonal spend variations

What counts as a saving#

A saving is logged when one of the following occurs:

The 15% commission#

Cloudlink charges 15% of your total verified savings each month. This commission only applies to savings that:

• Were detected and attributed to a Cloudlink action or alert
• Are verifiable from your cloud billing data
• Occurred within the billing month being invoiced

The commission is calculated on gross savings, before any Cloudlink fee. So if Cloudlink saves you $10,000, your invoice is $1,500 and you net $8,500.

Monthly invoices#

Invoices are generated on the 1st of each month for the previous month's savings. Each invoice includes:

• A line-by-line breakdown of every saving event counted in the month
• The type, date, resource, and dollar amount of each saving
• Total verified savings for the month
• The 15% commission amount
• Any rolled-over savings from prior months that brought you above the $500 threshold

Invoices are sent to the billing email on your account and are available in Settings → Billing.

The $500 minimum threshold#

Cloudlink only invoices you when your accumulated verified savings reach $500 or more in a billing month. This is to avoid billing you for trivial amounts and to reduce invoice overhead for smaller accounts.

If your savings for a month are below $500, they roll over to the next month and accumulate. You will be invoiced when the cumulative total reaches $500.

Example: You save $300 in January and $350 in February. The $300 rolls over, and in February you invoice on $650 total — a fee of $97.50.

Disputing a charge#

If you believe a saving has been incorrectly logged or attributed, you can dispute it directly from your invoice:

1. Go to Settings → Billing → Invoices
2. Find the saving event you want to dispute and click Dispute
3. Enter the reason for your dispute
4. Our team reviews disputes within 2 business days and responds via email

Disputed savings are held from that month's invoice until resolved. If the dispute is upheld, the saving is removed from your total and you are credited accordingly.

SDK — Installation#

The Cloudlink SDK allows you to attribute cloud costs to individual customers, features, or business units — without requiring perfect AWS tagging.

# Python
pip install cloudlink-sdk

# Node.js / TypeScript
npm install @cloudlink/sdk

SDK — Quick start#

from cloudlink import Cloudlink

# Initialise the client with your API key
cl = Cloudlink(api_key="cl_live_your_api_key_here")

# Track a unit of cost against a customer
cl.track(
    customer_id="customer_abc123",
    event="api_request",
    metadata={
        "feature": "data_export",
        "region": "us-east-1",
        "model": "gpt-4o",  # optional: useful for AI cost attribution
    }
)

print("Cost event tracked successfully")

import { Cloudlink } from '@cloudlink/sdk';

const cl = new Cloudlink({ apiKey: 'cl_live_your_api_key_here' });

// Track a cost event
await cl.track({
  customerId: 'customer_abc123',
  event: 'api_request',
  metadata: {
    feature: 'data_export',
    region: 'us-east-1',
  },
});

Tracking unit costs#

Use the SDK to attribute cloud costs to the specific customers and features driving them. This enables the Unit Economics dashboard to show you cost-per-customer and cost-per-feature breakdowns.

# Track with explicit cost attribution
cl.track(
    customer_id="customer_abc123",
    event="model_inference",
    cost_usd=0.00042,       # optional: provide if you know the exact cost
    metadata={
        "feature": "ai_summarisation",
        "model": "claude-3-5-sonnet",
        "input_tokens": 1200,
        "output_tokens": 340,
    }
)

# Bulk track multiple events
cl.track_batch([
    {"customer_id": "cust_001", "event": "api_request", "metadata": {"feature": "export"}},
    {"customer_id": "cust_002", "event": "api_request", "metadata": {"feature": "search"}},
    {"customer_id": "cust_003", "event": "model_inference", "metadata": {"feature": "ai_summarisation"}},
])

FastAPI middleware#

Add Cloudlink cost tracking to every FastAPI endpoint automatically using the middleware:

from fastapi import FastAPI
from cloudlink.middleware.fastapi import CloudlinkMiddleware

app = FastAPI()

# Add the middleware — tracks cost for every request
app.add_middleware(
    CloudlinkMiddleware,
    api_key="cl_live_your_api_key_here",
    # Extract customer ID from the Authorization header (JWT sub claim)
    customer_id_extractor=lambda request: request.state.user_id,
    # Map URL paths to feature names
    feature_map={
        "/api/v1/export": "data_export",
        "/api/v1/search": "search",
        "/api/v1/ai/summarise": "ai_summarisation",
    },
)

@app.get("/api/v1/export")
async def export_data():
    # Cost is tracked automatically — no manual tracking needed
    return {"status": "ok"}

Django middleware#

# settings.py
MIDDLEWARE = [
    "cloudlink.middleware.django.CloudlinkMiddleware",
    # ... your other middleware
]

CLOUDLINK = {
    "API_KEY": "cl_live_your_api_key_here",
    "CUSTOMER_ID_HEADER": "X-Customer-Id",  # or extract from JWT
    "FEATURE_MAP": {
        "/api/export/": "data_export",
        "/api/search/": "search",
    },
}

Configuration options#

API — Authentication#

All API requests must include your API key in the Authorization header:

curl https://api.cloudlinkglobal.com/v1/costs \
  -H "Authorization: Bearer YOUR_API_KEY"

API keys can be generated in Settings → API Keys. Keep your API key secret — do not expose it in client-side code or public repositories.

Security tip: Use environment variables to store API keys. Never commit them to version control. Rotate keys immediately if you suspect they have been exposed.

Base URL and versioning#

All API endpoints are versioned and served from a single base URL:

Base URL: https://api.cloudlinkglobal.com/v1

All responses are JSON. All timestamps are ISO 8601 in UTC. The API version is included in the URL path — we will maintain backward compatibility within a major version and provide advance notice before any breaking changes.

Rate limits#

API requests are rate limited per API key:

• Standard: 1,000 requests per hour
• Burst: 100 requests per minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1704067200

When rate limited, the API returns HTTP 429 with a Retry-After header indicating how many seconds to wait before retrying.

Endpoints — Dashboard#

Endpoints — Regressions#

Recording deploy events enables Cloudlink to attribute regressions to specific commits:

# Called from your CI/CD pipeline after a successful deploy
curl -X POST https://api.cloudlinkglobal.com/v1/deploys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "payments-api",
    "environment": "production",
    "version": "v2.14.1",
    "commit_sha": "a3f8c1d",
    "author": "platform@acme.dev",
    "deployed_at": "2025-03-15T14:32:00Z"
  }'

Endpoints — Resources#

Endpoints — Savings#

Error codes#

What is the MCP server?#

Cloudlink exposes your cost data as tools via the Model Context Protocol (MCP). This allows AI coding assistants like Claude and Cursor to answer questions about your cloud costs directly in your editor — without switching tabs.

Example queries you can ask your AI assistant:

• "What caused last week's spike in Lambda costs?"
• "Which service is trending up most this month?"
• "Show me my top 5 most wasteful resources right now"
• "What would my bill look like if I stopped these three EC2 instances?"
• "Are there any active cost regressions I should know about?"

Connecting to Claude#

Add the Cloudlink MCP server to your Claude Desktop configuration:

// ~/.config/claude/claude_desktop_config.json
{
  "mcpServers": {
    "cloudlink": {
      "command": "npx",
      "args": ["@cloudlink/mcp-server"],
      "env": {
        "CLOUDLINK_API_KEY": "cl_live_your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop after adding the configuration. You should see the Cloudlink tools listed in the Claude tools panel.

Connecting to Cursor#

Add the MCP server to your Cursor configuration file:

// .cursor/mcp.json (in your project root or home directory)
{
  "mcpServers": {
    "cloudlink": {
      "command": "npx",
      "args": ["@cloudlink/mcp-server"],
      "env": {
        "CLOUDLINK_API_KEY": "cl_live_your_api_key_here"
      }
    }
  }
}

Available tools#

The Cloudlink MCP server exposes the following tools to your AI assistant:

Slack alerts#

Connect Slack to receive real-time cost alerts in your engineering channels.

Setup

1. Go to Settings → Notifications → Slack
2. Click Connect Slack and authorise the Cloudlink app in your Slack workspace
3. Select the channel where alerts should be sent
4. Click Save

Alert format

Every Slack alert includes:

• The affected service name and environment
• The deploy that caused it (if applicable), including commit SHA and author
• The cost delta (% change and absolute $ amount)
• The estimated monthly impact
• A direct link to view the full regression in Cloudlink
• Approve / Reject buttons for suggested fixes (Slack Actions)

Alert thresholds

You can configure alert thresholds in Settings → Notifications → Slack. Only send alerts when:

• The cost impact exceeds a configurable threshold (default: $100/month)
• The regression severity is above a configurable level (low / medium / high / critical)
• Specific services or environments are affected

GitHub PR comments#

Cloudlink can post a cost impact comment on every pull request, showing the estimated cloud cost change the PR is likely to introduce based on historical data from similar changes.

Setup

1. Install the Cloudlink GitHub App from Settings → Integrations → GitHub
2. Authorise the app on your GitHub organisation
3. Select which repositories should receive PR cost comments

CI/CD webhook

For deploy attribution to work, add a step to your GitHub Actions workflow that notifies Cloudlink after each deploy:

# .github/workflows/deploy.yml
- name: Notify Cloudlink of deploy
  if: success()
  run: |
    curl -s -X POST ${{ secrets.CLOUDLINK_API_URL }}/v1/deploys \
      -H "Authorization: Bearer ${{ secrets.CLOUDLINK_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{
        "service": "${{ github.event.repository.name }}",
        "environment": "production",
        "commit_sha": "${{ github.sha }}",
        "author": "${{ github.actor }}",
        "version": "${{ github.ref_name }}"
      }'

Email notifications#

Email notifications are sent automatically to the account owner for:

• New critical regressions (cost spike over 100% or $5,000+ monthly impact)
• Monthly savings reports
• Invoice generation
• Dispute resolution updates

You can configure additional recipients and adjust notification preferences in Settings → Notifications → Email.

Webhooks#

Cloudlink can send webhook events to any HTTP endpoint when important events occur. This allows you to integrate cost events into your own tooling (PagerDuty, JIRA, custom dashboards, etc.).

Supported events

• regression.created — new cost regression detected
• regression.resolved — regression marked as resolved
• saving.logged — new saving event recorded
• resource.idle_detected — idle resource found
• invoice.generated — monthly invoice created

Webhook payload

{
  "event": "regression.created",
  "timestamp": "2025-03-15T14:32:00Z",
  "data": {
    "regression_id": "reg_abc123",
    "service": "payments-lambda",
    "environment": "production",
    "delta_pct": 142,
    "monthly_impact_usd": 2840,
    "attributed_deploy": {
      "commit_sha": "a3f8c1d",
      "author": "platform@acme.dev",
      "deployed_at": "2025-03-15T12:00:00Z"
    }
  }
}

Webhook security

Every webhook request includes a signature header for verification:

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    """Verify the Cloudlink webhook signature."""
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)