Datadog APM API
Datadog APM REST API for traces, spans, services, service definitions, and SLOs. Provides endpoints for searching traces, managing service catalog entries, and configuring service level objectives.
OpenAPI Specification
openapi: 3.1.0
info:
title: Datadog APM API
description: >-
Datadog APM REST API for traces, services, service definitions, and SLOs.
Provides endpoints for searching and retrieving distributed traces,
managing service catalog entries, and configuring service level objectives.
version: 1.0.0
contact:
name: Datadog
url: https://www.datadoghq.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://api.datadoghq.com
description: Datadog US1 site
- url: https://api.datadoghq.eu
description: Datadog EU site
- url: https://api.us3.datadoghq.com
description: Datadog US3 site
- url: https://api.us5.datadoghq.com
description: Datadog US5 site
security:
- apiKeyAuth: []
appKeyAuth: []
paths:
/api/v1/traces:
get:
operationId: listTraces
summary: List traces
description: >-
Search and retrieve traces. Returns a list of traces matching the
given search criteria.
tags:
- Traces
parameters:
- name: query
in: query
description: Search query for traces
schema:
type: string
- name: start
in: query
description: Start of the time range in epoch seconds
schema:
type: integer
- name: end
in: query
description: End of the time range in epoch seconds
schema:
type: integer
- name: limit
in: query
description: Maximum number of traces to return
schema:
type: integer
default: 50
responses:
'200':
description: A list of traces
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Trace'
'400':
description: Bad request
'403':
description: Forbidden
/api/v2/spans/events/search:
post:
operationId: searchSpans
summary: Search spans
description: >-
Search or aggregate spans from your Datadog platform. Returns spans
matching the search criteria.
tags:
- Spans
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SpansSearchRequest'
responses:
'200':
description: Span search results
content:
application/json:
schema:
$ref: '#/components/schemas/SpansSearchResponse'
'400':
description: Bad request
'403':
description: Forbidden
/api/v2/spans:
post:
operationId: aggregateSpans
summary: Aggregate spans
description: Aggregate spans matching a search query grouped by facets.
tags:
- Spans
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SpansAggregateRequest'
responses:
'200':
description: Aggregation results
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
type:
type: string
attributes:
type: object
'400':
description: Bad request
'403':
description: Forbidden
/api/v1/service_dependencies:
get:
operationId: getServiceDependencies
summary: Get service dependencies
description: Get the list of service dependencies for your organization.
tags:
- Services
parameters:
- name: env
in: query
required: true
description: The environment to query
schema:
type: string
- name: start
in: query
description: Start time in epoch seconds
schema:
type: integer
- name: end
in: query
description: End time in epoch seconds
schema:
type: integer
responses:
'200':
description: Service dependency map
content:
application/json:
schema:
type: object
additionalProperties:
type: array
items:
type: string
'400':
description: Bad request
'403':
description: Forbidden
/api/v2/services/definitions:
get:
operationId: listServiceDefinitions
summary: List service definitions
description: >-
Get a list of all service definitions in the Datadog Service Catalog.
tags:
- Service Definitions
parameters:
- name: page[size]:
in: query
description: Number of results per page
schema:
type: integer
default: 10
- name: page[number]:
in: query
description: Page number
schema:
type: integer
- name: schema_version
in: query
description: Filter by schema version (v1, v2, v2.1, v2.2)
schema:
type: string
enum:
- v1
- v2
- v2.1
- v2.2
responses:
'200':
description: List of service definitions
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceDefinitionsListResponse'
'403':
description: Forbidden
post:
operationId: createOrUpdateServiceDefinition
summary: Create or update a service definition
description: >-
Create or update a service definition in the Datadog Service Catalog.
tags:
- Service Definitions
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceDefinition'
responses:
'200':
description: Service definition created or updated
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceDefinitionCreateResponse'
'400':
description: Bad request
'403':
description: Forbidden
'409':
description: Conflict
/api/v2/services/definitions/{service_name}:
get:
operationId: getServiceDefinition
summary: Get a service definition
description: Get a single service definition from the Datadog Service Catalog.
tags:
- Service Definitions
parameters:
- name: service_name
in: path
required: true
description: The name of the service
schema:
type: string
- name: schema_version
in: query
description: Schema version to return
schema:
type: string
responses:
'200':
description: Service definition
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceDefinitionGetResponse'
'404':
description: Service not found
delete:
operationId: deleteServiceDefinition
summary: Delete a service definition
description: Delete a service definition from the Datadog Service Catalog.
tags:
- Service Definitions
parameters:
- name: service_name
in: path
required: true
schema:
type: string
responses:
'204':
description: Service definition deleted
'404':
description: Service not found
/api/v1/slo:
get:
operationId: listSLOs
summary: List SLOs
description: Get a list of service level objective objects for your organization.
tags:
- SLOs
parameters:
- name: ids
in: query
description: Comma-separated list of SLO IDs
schema:
type: string
- name: query
in: query
description: Search query for filtering SLOs
schema:
type: string
- name: tags_query
in: query
description: Filter SLOs by tags
schema:
type: string
- name: metrics_query
in: query
description: Filter SLOs by metrics query
schema:
type: string
- name: limit
in: query
description: Maximum number of SLOs to return
schema:
type: integer
default: 1000
- name: offset
in: query
description: Pagination offset
schema:
type: integer
responses:
'200':
description: List of SLOs
content:
application/json:
schema:
$ref: '#/components/schemas/SLOListResponse'
'400':
description: Bad request
'403':
description: Forbidden
post:
operationId: createSLO
summary: Create a SLO
description: Create a service level objective object.
tags:
- SLOs
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SLO'
responses:
'200':
description: SLO created
content:
application/json:
schema:
$ref: '#/components/schemas/SLOResponse'
'400':
description: Bad request
'403':
description: Forbidden
/api/v1/slo/{slo_id}:
get:
operationId: getSLO
summary: Get a SLO
description: Get a service level objective by ID.
tags:
- SLOs
parameters:
- name: slo_id
in: path
required: true
schema:
type: string
- name: with_configured_alert_ids
in: query
description: Include configured alert IDs
schema:
type: boolean
responses:
'200':
description: SLO details
content:
application/json:
schema:
$ref: '#/components/schemas/SLOResponse'
'403':
description: Forbidden
'404':
description: SLO not found
put:
operationId: updateSLO
summary: Update a SLO
description: Update an existing service level objective.
tags:
- SLOs
parameters:
- name: slo_id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SLO'
responses:
'200':
description: SLO updated
content:
application/json:
schema:
$ref: '#/components/schemas/SLOResponse'
'400':
description: Bad request
'403':
description: Forbidden
'404':
description: SLO not found
delete:
operationId: deleteSLO
summary: Delete a SLO
description: Permanently delete a service level objective.
tags:
- SLOs
parameters:
- name: slo_id
in: path
required: true
schema:
type: string
- name: force
in: query
description: Force delete even if referenced by monitors
schema:
type: string
responses:
'200':
description: SLO deleted
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
deleted:
type: array
items:
type: string
'403':
description: Forbidden
'404':
description: SLO not found
'409':
description: Conflict - SLO is referenced
/api/v1/slo/{slo_id}/history:
get:
operationId: getSLOHistory
summary: Get SLO history
description: Get the SLO history data for a given SLO.
tags:
- SLOs
parameters:
- name: slo_id
in: path
required: true
schema:
type: string
- name: from_ts
in: query
required: true
description: Start of history window in epoch seconds
schema:
type: integer
- name: to_ts
in: query
required: true
description: End of history window in epoch seconds
schema:
type: integer
responses:
'200':
description: SLO history
content:
application/json:
schema:
$ref: '#/components/schemas/SLOHistoryResponse'
'400':
description: Bad request
'403':
description: Forbidden
'404':
description: SLO not found
components:
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: DD-API-KEY
appKeyAuth:
type: apiKey
in: header
name: DD-APPLICATION-KEY
schemas:
Trace:
type: object
properties:
traceId:
type: string
spans:
type: array
items:
$ref: '#/components/schemas/APMSpan'
APMSpan:
type: object
properties:
traceId:
type: string
description: 64-bit trace ID
spanId:
type: string
description: 64-bit span ID
parentId:
type: string
description: 64-bit parent span ID
name:
type: string
description: Operation name
service:
type: string
description: Service name
resource:
type: string
description: Resource name (e.g., URL, query)
type:
type: string
description: Span type (web, db, cache, custom)
start:
type: integer
description: Start time in nanoseconds since epoch
duration:
type: integer
description: Duration in nanoseconds
error:
type: integer
description: Error flag (0 or 1)
meta:
type: object
description: String key-value tags
additionalProperties:
type: string
metrics:
type: object
description: Numeric key-value metrics
additionalProperties:
type: number
SpansSearchRequest:
type: object
properties:
data:
type: object
properties:
type:
type: string
enum:
- search_request
attributes:
type: object
properties:
filter:
type: object
properties:
query:
type: string
description: Search query string
from:
type: string
description: Start time (ISO 8601 or relative)
to:
type: string
description: End time (ISO 8601 or relative)
sort:
type: string
description: Sort order for results
enum:
- timestamp
- '-timestamp'
page:
type: object
properties:
cursor:
type: string
limit:
type: integer
default: 10
maximum: 1000
SpansSearchResponse:
type: object
properties:
data:
type: array
items:
type: object
properties:
type:
type: string
id:
type: string
attributes:
type: object
properties:
service:
type: string
resource_name:
type: string
span_id:
type: string
trace_id:
type: string
timestamp:
type: string
duration:
type: integer
status:
type: string
tags:
type: object
additionalProperties:
type: string
meta:
type: object
properties:
page:
type: object
properties:
after:
type: string
SpansAggregateRequest:
type: object
properties:
data:
type: object
properties:
type:
type: string
enum:
- aggregate_request
attributes:
type: object
properties:
filter:
type: object
properties:
query:
type: string
from:
type: string
to:
type: string
group_by:
type: array
items:
type: object
properties:
facet:
type: string
limit:
type: integer
sort:
type: object
compute:
type: array
items:
type: object
properties:
aggregation:
type: string
enum:
- count
- avg
- sum
- min
- max
- pct
metric:
type: string
type:
type: string
ServiceDefinitionsListResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ServiceDefinitionData'
ServiceDefinitionData:
type: object
properties:
type:
type: string
id:
type: string
attributes:
type: object
properties:
meta:
type: object
properties:
last_modified_time:
type: string
github_html_url:
type: string
schema:
$ref: '#/components/schemas/ServiceDefinition'
ServiceDefinition:
type: object
properties:
schema-version:
type: string
enum:
- v2
- v2.1
- v2.2
dd-service:
type: string
description: Unique service name
team:
type: string
description: Team that owns the service
description:
type: string
tier:
type: string
lifecycle:
type: string
enum:
- production
- staging
- development
- deprecated
application:
type: string
contacts:
type: array
items:
type: object
properties:
name:
type: string
type:
type: string
enum:
- email
- slack
- microsoft-teams
contact:
type: string
links:
type: array
items:
type: object
properties:
name:
type: string
type:
type: string
enum:
- doc
- repo
- runbook
- dashboard
- oncall
- code
- link
url:
type: string
format: uri
repos:
type: array
items:
type: object
properties:
name:
type: string
url:
type: string
format: uri
provider:
type: string
tags:
type: array
items:
type: string
integrations:
type: object
properties:
pagerduty:
type: object
properties:
service-url:
type: string
format: uri
opsgenie:
type: object
properties:
service-url:
type: string
format: uri
region:
type: string
enum:
- US
- EU
ServiceDefinitionCreateResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ServiceDefinitionData'
ServiceDefinitionGetResponse:
type: object
properties:
data:
$ref: '#/components/schemas/ServiceDefinitionData'
SLO:
type: object
required:
- name
- type
- thresholds
properties:
name:
type: string
description: Name of the SLO
description:
type: string
type:
type: string
enum:
- metric
- monitor
- time_slice
thresholds:
type: array
items:
$ref: '#/components/schemas/SLOThreshold'
monitor_ids:
type: array
description: Required for monitor-based SLOs
items:
type: integer
query:
type: object
description: Required for metric-based SLOs
properties:
numerator:
type: string
denominator:
type: string
sli_specification:
type: object
description: Required for time-slice SLOs
properties:
time_slice:
type: object
properties:
query:
type: object
properties:
formulas:
type: array
items:
type: object
properties:
formula:
type: string
queries:
type: array
items:
type: object
comparator:
type: string
enum:
- '>'
- '>='
- <
- <=
threshold:
type: number
tags:
type: array
items:
type: string
target_threshold:
type: number
timeframe:
type: string
enum:
- 7d
- 30d
- 90d
- custom
SLOThreshold:
type: object
required:
- target
- timeframe
properties:
target:
type: number
description: Target percentage (0-100)
target_display:
type: string
timeframe:
type: string
enum:
- 7d
- 30d
- 90d
- custom
warning:
type: number
warning_display:
type: string
SLOListResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/SLOResponse'
metadata:
type: object
properties:
page:
type: object
properties:
total_count:
type: integer
total_filtered_count:
type: integer
SLOResponse:
type: object
properties:
data:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
type:
type: string
thresholds:
type: array
items:
$ref: '#/components/schemas/SLOThreshold'
tags:
type: array
items:
type: string
creator:
type: object
properties:
name:
type: string
email:
type: string
created_at:
type: integer
modified_at:
type: integer
errors:
type: array
items:
type: string
SLOHistoryResponse:
type: object
properties:
data:
type: object
properties:
from_ts:
type: integer
to_ts:
type: integer
type:
type: string
type_id:
type: integer
overall:
type: object
properties:
sli_value:
type: number
span_precision:
type: number
name:
type: string
precision:
type: object
additionalProperties:
type: number
thresholds:
type: object
additionalProperties:
type: object
properties:
target:
type: number
timeframe:
type: string
errors:
type: array
items:
type: string