Sentry API and CLI Reference

REST API

Base URLs

Authentication

# Bearer token (recommended)
curl -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  https://sentry.io/api/0/organizations/

# DSN-based auth (limited to event submission)
curl -H "Authorization: DSN https://public@sentry.io/1" \
  https://sentry.io/api/0/...

Create auth tokens at: Settings > Auth Tokens (or sentry.io/settings/auth-tokens/).

Key API endpoints

Resolve an issue via API

curl -X PUT \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}' \
  https://sentry.io/api/0/issues/12345/

Create a release via API

curl -X POST \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "my-app@1.2.0",
    "projects": ["my-project"]
  }' \
  https://sentry.io/api/0/organizations/my-org/releases/

Pagination

API responses use cursor-based pagination via the Link header:

Link: <https://sentry.io/api/0/...?cursor=next_cursor>; rel="next"; results="true"

Check results="true" to determine if more pages exist.

Rate limits

The API returns 429 Too Many Requests when rate limited. Check the Retry-After header for the number of seconds to wait.

Sentry CLI (sentry-cli)

Installation

# npm (recommended for JS projects)
npm install -g @sentry/cli

# Homebrew (macOS)
brew install getsentry/tools/sentry-cli

# curl (Linux/macOS)
curl -sL https://sentry.io/get-cli/ | bash

# Docker
docker pull getsentry/sentry-cli

Configuration

Create a .sentryclirc file at project root or home directory:

[auth]
token=sntrys_YOUR_TOKEN_HERE

[defaults]
org=your-org-slug
project=your-project-slug
url=https://sentry.io/

Or use environment variables:

export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE
export SENTRY_ORG=your-org-slug
export SENTRY_PROJECT=your-project-slug

Key commands

Release management

# Create a new release
sentry-cli releases new my-app@1.2.0

# Associate commits with a release
sentry-cli releases set-commits my-app@1.2.0 --auto

# Mark a release as deployed
sentry-cli releases deploys my-app@1.2.0 new -e production

# Finalize a release
sentry-cli releases finalize my-app@1.2.0

Source maps

# Upload source maps for a release
sentry-cli sourcemaps upload --release=my-app@1.2.0 ./dist

# Upload with URL prefix for hosted apps
sentry-cli sourcemaps upload --release=my-app@1.2.0 \
  --url-prefix="~/static/js" ./build/static/js

# Validate source maps before uploading
sentry-cli sourcemaps explain --release=my-app@1.2.0

Debug files (native apps)

# Upload debug symbols (iOS dSYMs, Android debug files)
sentry-cli debug-files upload ./path/to/dsyms

# Check what debug files exist for a project
sentry-cli debug-files check

Cron monitoring

# Wrap a cron job for automatic monitoring
sentry-cli monitors run my-cron-slug -- /path/to/script.sh

# Send manual check-ins
sentry-cli monitors check-in my-cron-slug --status=ok
sentry-cli monitors check-in my-cron-slug --status=error

Send test events

# Send a test event to verify setup
sentry-cli send-event -m "Test event from CLI"

Sentry Next.js Integration Guide

Quick setup with wizard

npx @sentry/wizard@latest -i nextjs

The wizard creates all necessary files and prompts for feature selection (Error Monitoring, Logs, Session Replay, Tracing).

Files created by the wizard

instrumentation-client.ts (browser-side)

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  sendDefaultPii: true,
  tracesSampleRate: process.env.NODE_ENV === "development" ? 1.0 : 0.1,
  replaysSessionSampleRate: 0.1,
  replaysOnErrorSampleRate: 1.0,
  enableLogs: true,
  integrations: [Sentry.replayIntegration()],
});

instrumentation.ts (server + edge registration)

import * as Sentry from "@sentry/nextjs";

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("./sentry.server.config");
  }
  if (process.env.NEXT_RUNTIME === "edge") {
    await import("./sentry.edge.config");
  }
}

export const onRequestError = Sentry.captureRequestError;

sentry.server.config.ts

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
  enableLogs: true,
});

sentry.edge.config.ts

import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0,
});

next.config.ts wrapper

import type { NextConfig } from "next";
import { withSentryConfig } from "@sentry/nextjs";

const nextConfig: NextConfig = {
  // your existing config
};

export default withSentryConfig(nextConfig, {
  org: process.env.SENTRY_ORG,
  project: process.env.SENTRY_PROJECT,
  authToken: process.env.SENTRY_AUTH_TOKEN,

  // Route browser requests through your server to avoid ad blockers
  tunnelRoute: "/monitoring",

  // Suppress build output unless in CI
  silent: !process.env.CI,

  // Automatically upload source maps during build
  // Source maps are deleted from the build output after upload
});

app/global-error.tsx (React error boundary)

"use client";

import * as Sentry from "@sentry/nextjs";
import { useEffect } from "react";

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    Sentry.captureException(error);
  }, [error]);

  return (
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => reset()}>Try again</button>
      </body>
    </html>
  );
}

Environment variables

# Required
NEXT_PUBLIC_SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0
SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0
SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE
SENTRY_ORG=your-org-slug
SENTRY_PROJECT=your-project-slug

NEXT_PUBLIC_SENTRY_DSN is needed for client-side, SENTRY_DSN for server-side. SENTRY_AUTH_TOKEN is only needed at build time for source map upload.

Structured logging

import * as Sentry from "@sentry/nextjs";

Sentry.logger.info("User completed checkout", { orderId: "123" });
Sentry.logger.warn("Payment retry attempted", { attempt: 2 });
Sentry.logger.error("Payment failed", { reason: "insufficient_funds" });

Key gotchas

• The tunnelRoute option routes Sentry requests through your Next.js server, avoiding ad blockers. The default /monitoring path should not conflict with your app routes.
• Source maps are automatically uploaded during next build and then deleted from the output. They never reach your production server.
• Adjust tracesSampleRate for production traffic - development uses 1.0 by default, but production should typically use 0.1 or lower.
• The onRequestError export in instrumentation.ts captures server-side rendering errors automatically.

Sentry SDK Configuration Reference

JavaScript SDK (@sentry/browser, @sentry/node, @sentry/nextjs)

Core options

Tracing options

Replay options

Profiling options

Integrations

import * as Sentry from "@sentry/browser";

Sentry.init({
  integrations: [
    // Performance tracing - auto-instruments page loads and navigation
    Sentry.browserTracingIntegration(),

    // Session replay - records DOM state as video-like reproduction
    Sentry.replayIntegration({
      maskAllText: true,
      blockAllMedia: true,
      maskAllInputs: true,
    }),

    // User feedback widget
    Sentry.feedbackIntegration({
      colorScheme: "system",
    }),
  ],
});

Hooks and callbacks

Sentry.init({
  // Filter events before sending
  beforeSend(event, hint) {
    if (event.exception?.values?.[0]?.type === "NetworkError") {
      return null; // Drop this event
    }
    return event;
  },

  // Filter breadcrumbs
  beforeBreadcrumb(breadcrumb, hint) {
    if (breadcrumb.category === "console") {
      return null; // Drop console breadcrumbs
    }
    return breadcrumb;
  },

  // Filter transactions
  beforeSendTransaction(event) {
    if (event.transaction === "/health") {
      return null; // Drop health check transactions
    }
    return event;
  },
});

Python SDK (sentry-sdk)

Core options

Framework auto-detection

The Python SDK auto-detects and integrates with frameworks:

• Django - middleware, template errors, signals
• Flask - request context, error handlers
• FastAPI - ASGI middleware, request tracing
• Celery - task monitoring, error capture
• SQLAlchemy - query spans
• Redis - command spans
• httpx/requests - outgoing HTTP spans

Hooks and callbacks

import sentry_sdk

def before_send(event, hint):
    if "exc_info" in hint:
        exc_type, exc_value, tb = hint["exc_info"]
        if isinstance(exc_value, KeyboardInterrupt):
            return None  # Drop keyboard interrupts
    return event

sentry_sdk.init(
    dsn="...",
    before_send=before_send,
)

Recommended production sample rates

Always set replaysOnErrorSampleRate: 1.0 in production to capture all error sessions with replay context.