A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Datadog API is how an app or AI agent works with a Datadog account: submitting and querying metrics, creating and editing monitors, searching logs, opening incidents, and reading the hosts that report in. Access is granted through an API key that identifies the organization, plus an application key for endpoints that read or manage data, and that application key can be limited to scopes that set which areas a call may reach. Datadog runs two API versions side by side, and it organizes everything by observability area, each with its own scope.
How an app or AI agent connects to Datadog determines what it can reach. There is a route for making calls, a route for receiving data, and a hosted server that exposes Datadog tools to agents, and each is governed by the keys behind it and the scopes those keys carry.
The REST API answers at api.datadoghq.com (and regional sites such as api.datadoghq.eu, api.us5.datadoghq.com, and others). It runs two versions side by side: older areas under v1 and newer areas under v2. A call authenticates with an API key in the DD-API-KEY header, and read endpoints also require an application key in the DD-APPLICATION-KEY header. Some submission endpoints use a dedicated intake host, like http-intake.logs.datadoghq.com for logs.
Datadog's hosted MCP server gives an AI agent live access to observability data and tools, covering APM, logs, metrics, monitors, dashboards, security signals, and more. It went generally available on 10 March 2026. The endpoint is the per-site MCP host, like https://mcp.datadoghq.com, and a toolsets query parameter enables specific tool groups. It authenticates with OAuth 2.0, or with an API key and application key sent as DD_API_KEY and DD_APPLICATION_KEY headers.
An API key identifies the organization and is required on every request, sent in the DD-API-KEY header. Data submission endpoints, like sending metrics, logs, and posting events, need only the API key. An organization has between one and 50 API keys.
An application key is required, alongside the API key, on endpoints that read or manage data, sent in the DD-APPLICATION-KEY header. By default it inherits the permissions of the user or service account that created it. It is the key that carries scopes.
An application key can be restricted to authorization scopes, like metrics_read, monitors_write, dashboards_read, logs_read_data, or incident_write, so it reaches only the data and actions those scopes name. Scoping follows least privilege, and a key with no matching scope is refused. This is the least-privilege choice for connecting to Datadog.
OAuth 2.0 lets a third-party integration connect to a Datadog organization with the account owner's consent, granting access to a set of scopes rather than sharing raw keys. The Datadog MCP server uses OAuth 2.0 for authentication.
The Datadog API is split into areas an agent can act on, like metrics, monitors, dashboards, logs, incidents, and hosts. Each area has its own methods and its own scope, and writes in some areas page on-call people or silence alerting.
Submit metric points, query timeseries and scalar data, list active metrics, and read a metric's metadata and tags.
Create, read, list, edit, and delete monitors, the alert definitions that watch metrics, logs, and more.
Create, read, list, update, and delete dashboards.
Send logs over HTTP, search and list log events, and aggregate them into analytics.
Post an event to the events stream, and list, search, and read events.
Create, read, list, update, search, and delete incidents.
Schedule, read, list, update, and cancel downtimes, the windows that mute monitor alerting.
Create, read, list, update, and delete service level objectives, and read an objective's history.
List hosts, read the active-host totals, and mute or unmute a single host.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
MetricsSubmit metric points, query timeseries and scalar data, list active metrics, and read a metric's metadata and tags.6 | ||||||
| POST | /api/v2/series | Submit metric points so they can be graphed on dashboards. | write | — | Current | |
Submission needs only the API key (DD-API-KEY), no application key or scope. Data point submission is not rate limited. Acts onmetric Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/query/timeseries | Query timeseries data across multiple Datadog products. | read | timeseries_query | Current | |
The timeseries_query scope also covers the v1 query endpoint and scalar queries. Acts onmetric Permission (capability) timeseries_queryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/query/scalar | Query scalar values across multiple Datadog products. | read | timeseries_query | Current | |
Returns a single computed value per query rather than a series. Acts onmetric Permission (capability) timeseries_queryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/query | Query timeseries points over a time range (the older v1 metrics query). | read | timeseries_query | Current | |
The v1 query endpoint, superseded by the v2 timeseries query but still supported. Acts onmetric Permission (capability) timeseries_queryVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/metrics | Get the list of metrics actively reporting in a time window. | read | metrics_read | Current | |
Read-only. Acts onmetric Permission (capability) metrics_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/metrics/{metric_name} | Get the metadata for a metric, like its unit and description. | read | metrics_read | Current | |
Read-only. Acts onmetric Permission (capability) metrics_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MonitorsCreate, read, list, edit, and delete monitors, the alert definitions that watch metrics, logs, and more.5 | ||||||
| POST | /api/v1/monitor | Create a monitor. | write | monitors_write | Current | |
A core write; creates an alert definition that can page people. Acts onmonitor Permission (capability) monitors_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/monitor/{monitor_id} | Get a single monitor's details. | read | monitors_read | Current | |
Read-only. Acts onmonitor Permission (capability) monitors_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/monitor | Get all monitors, with optional filtering. | read | monitors_read | Current | |
Read-only. Acts onmonitor Permission (capability) monitors_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/monitor/{monitor_id} | Edit an existing monitor. | write | monitors_write | Current | |
Can change thresholds, message, and notification targets. Acts onmonitor Permission (capability) monitors_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/monitor/{monitor_id} | Delete a monitor. | write | monitors_write | Current | |
Removes the alert definition; existing alerting stops. Acts onmonitor Permission (capability) monitors_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DashboardsCreate, read, list, update, and delete dashboards.5 | ||||||
| POST | /api/v1/dashboard | Create a dashboard. | write | dashboards_write | Current | |
A core catalog write. Acts ondashboard Permission (capability) dashboards_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/dashboard/{dashboard_id} | Get a dashboard. | read | dashboards_read | Current | |
Read-only. Acts ondashboard Permission (capability) dashboards_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/dashboard | Get all dashboards. | read | dashboards_read | Current | |
Read-only. Acts ondashboard Permission (capability) dashboards_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/dashboard/{dashboard_id} | Update a dashboard. | write | dashboards_write | Current | |
Overwrites the dashboard definition. Acts ondashboard Permission (capability) dashboards_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/dashboard/{dashboard_id} | Delete a dashboard. | write | dashboards_write | Current | |
Irreversible. Acts ondashboard Permission (capability) dashboards_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
LogsSend logs over HTTP, search and list log events, and aggregate them into analytics.4 | ||||||
| POST | /api/v2/logs | Send logs over HTTP to the log intake endpoint. | write | — | Current | |
Intake needs only the API key (DD-API-KEY), no application key or scope, and goes to the http-intake.logs host. Log submission is not rate limited. Acts onlog Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/logs/events/search | Search log events with a structured query body. | read | logs_read_data | Current | |
The logs_read_data scope returns log content, which can include sensitive data captured in logs. Acts onlog Permission (capability) logs_read_dataVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/logs/events | Get a list of log events with query parameters. | read | logs_read_data | Current | |
Read-only; the GET form of the search endpoint. Acts onlog Permission (capability) logs_read_dataVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/logs/analytics/aggregate | Aggregate log events into computed analytics buckets. | read | logs_read_data | Current | |
Read-only; returns counts and aggregates rather than raw log lines. Acts onlog Permission (capability) logs_read_dataVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
EventsPost an event to the events stream, and list, search, and read events.4 | ||||||
| POST | /api/v1/events | Post an event to the events stream. | write | — | Current | |
The v1 post needs only the API key (DD-API-KEY), no application key or scope. Event submission is capped at 250,000 events per minute per organization. Acts onevent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit250,000 events/min per org SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/events | Get a list of events from the events stream. | read | events_read | Current | |
Read-only; the v2 events list. Acts onevent Permission (capability) events_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/events/search | Search events with a structured query body. | read | events_read | Current | |
Read-only. Acts onevent Permission (capability) events_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/events/{event_id} | Get the details of a single event. | read | events_read | Current | |
Read-only. Acts onevent Permission (capability) events_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
IncidentsCreate, read, list, update, search, and delete incidents.6 | ||||||
| POST | /api/v2/incidents | Create an incident. | write | incident_write | Current | |
A core write; opens an incident record people coordinate around. Acts onincident Permission (capability) incident_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/incidents/{incident_id} | Get the details of an incident. | read | incident_read | Current | |
Read-only. Acts onincident Permission (capability) incident_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/incidents | Get a list of incidents. | read | incident_read | Current | |
Read-only. Acts onincident Permission (capability) incident_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/incidents/{incident_id} | Update an incident's attributes. | write | incident_write | Current | |
Can change state, severity, and assigned fields. Acts onincident Permission (capability) incident_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/incidents/search | Search for incidents matching a query. | read | incident_read | Current | |
Read-only. Acts onincident Permission (capability) incident_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/incidents/{incident_id} | Delete an incident. | write | incident_write | Current | |
Irreversible. Acts onincident Permission (capability) incident_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DowntimesSchedule, read, list, update, and cancel downtimes, the windows that mute monitor alerting.5 | ||||||
| POST | /api/v2/downtime | Schedule a downtime to mute monitor alerting for a scope. | write | monitors_downtime | Current | |
The monitors_downtime scope silences alerts for the scoped monitors during the window. Acts ondowntime Permission (capability) monitors_downtimeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/downtime/{downtime_id} | Get a downtime's details. | read | monitors_downtime | Current | |
The same monitors_downtime scope governs reading and writing downtimes. Acts ondowntime Permission (capability) monitors_downtimeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/downtime | Get all scheduled downtimes. | read | monitors_downtime | Current | |
Lists active and scheduled downtimes. Acts ondowntime Permission (capability) monitors_downtimeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/downtime/{downtime_id} | Update a downtime's schedule or scope. | write | monitors_downtime | Current | |
Can extend or change which monitors are muted. Acts ondowntime Permission (capability) monitors_downtimeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/downtime/{downtime_id} | Cancel a downtime so alerting resumes. | write | monitors_downtime | Current | |
Ends the mute window early and re-enables alerting. Acts ondowntime Permission (capability) monitors_downtimeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Service Level ObjectivesCreate, read, list, update, and delete service level objectives, and read an objective's history.6 | ||||||
| POST | /api/v1/slo | Create a service level objective. | write | slos_write | Current | |
A core write; defines a reliability target and its budget. Acts onslo Permission (capability) slos_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/slo/{slo_id} | Get a service level objective's details. | read | slos_read | Current | |
Read-only. Acts onslo Permission (capability) slos_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/slo | Get a list of service level objectives. | read | slos_read | Current | |
Read-only. Acts onslo Permission (capability) slos_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/slo/{slo_id} | Update a service level objective. | write | slos_write | Current | |
Overwrites the objective definition. Acts onslo Permission (capability) slos_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/slo/{slo_id} | Delete a service level objective. | write | slos_write | Current | |
Irreversible. Acts onslo Permission (capability) slos_writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/slo/{slo_id}/history | Get a service level objective's status history over a time range. | read | slos_read | Current | |
Read-only; returns the achieved level and error budget over the window. Acts onslo Permission (capability) slos_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
HostsList hosts, read the active-host totals, and mute or unmute a single host.4 | ||||||
| GET | /api/v1/hosts | Get the list of reporting hosts. | read | hosts_read | Current | |
Read-only. Acts onhost Permission (capability) hosts_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/hosts/totals | Get the total number of active and up hosts. | read | hosts_read | Current | |
Read-only. Acts onhost Permission (capability) hosts_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/host/{host_name}/mute | Mute a host so its monitors stop alerting. | write | hosts_read | Current | |
Muting and unmuting a host both fall under the hosts_read scope, even though they change alerting. Acts onhost Permission (capability) hosts_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/host/{host_name}/unmute | Unmute a host so its monitors alert again. | write | hosts_read | Current | |
Re-enables alerting for the host. Acts onhost Permission (capability) hosts_readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Datadog sends data out through its own integrations rather than a single webhook feed. A monitor or an event can route a notification to a chosen destination, like Slack, email, or a generic webhook integration, when an alert triggers.
| Event | What it signals | Triggered by |
|---|
Datadog limits how fast an app or AI agent can call most read endpoints, while data submission for metrics and logs is not rate limited, and it reports the current state through a set of response headers.
Datadog rate limits many read and management endpoints, while data submission is treated separately: metric point submission and the log intake are not rate limited, and event submission is capped at 250,000 events per minute per organization. The limit on a rate-limited endpoint varies by endpoint and can be raised on request. Every rate-limited response carries a set of headers that report the current state: X-RateLimit-Limit is how many requests are allowed in the period, X-RateLimit-Period is the reset window in seconds, X-RateLimit-Remaining is how many requests are left, X-RateLimit-Reset is the seconds until the next reset, and X-RateLimit-Name identifies the limit for an increase request. Exceeding a limit returns HTTP 429, and a caller should wait the period before calling again or settle into a rate just under the limit.
List endpoints page through results, with the model depending on the area. Many v2 endpoints, like logs and events, use cursor-based pagination, returning a cursor in the response metadata to pass on the next request, while some v1 endpoints page by an offset or a page index. Each endpoint's reference page documents its own page-size parameter and default.
Page sizes are set per endpoint, with logs and events search commonly defaulting to a modest page and allowing a larger maximum. The HTTP log intake accepts a payload up to 5 MB per request and up to 1,000 log entries per array, and a single log entry is capped at 1 MB. Specific size ceilings are documented on each endpoint's reference page.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed, like an invalid query, a missing required field, or a body that fails validation. | Read the errors array in the response, correct the request, and resend. |
| 403 | Forbidden | Authentication failed or access was denied. The API key or application key is missing or invalid, or the application key lacks a scope the endpoint requires. | Confirm both keys are sent and valid, and grant the application key the scope the endpoint needs. |
| 404 | Not Found | The requested resource does not exist, or the keys cannot see it. | Verify the path and identifier, and confirm the keys belong to the right organization and site. |
| 429 | Too Many Requests | A rate limit was exceeded on a rate-limited endpoint. The X-RateLimit headers describe the limit and when it resets. | Wait for the period named in X-RateLimit-Period or X-RateLimit-Reset, then retry, and slow the call rate. |
Datadog runs two API versions side by side. The older v1 endpoints and the newer v2 endpoints coexist, and a given area lives under whichever version documents it, with newer areas built on v2.
Datadog's v2 API is the current generation, used for newer areas and for the modern form of migrated areas. It follows a JSON:API-style envelope with a data object carrying a type and attributes. Newer areas, such as incidents, downtimes (current form), event management, and the multi-product timeseries and scalar queries, are built on v2, while older areas remain on v1. There is no dated version string to pin; each endpoint is called at the version its reference page documents.
The v1 API is the original generation and remains supported for the areas that still live on it. Monitors, dashboards, hosts, service level objectives, the v1 metrics query, and active-metrics and metadata reads are served by v1. Datadog continues to migrate areas to v2 over time, but v1 endpoints stay available where no v2 form exists.
An integration calls each endpoint at the version its reference page documents, mixing v1 and v2 as needed.
Datadog API reference ↗Bollard AI sits between a team's AI agents and Datadog. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.