openapi: 3.0.0
info:
contact:
email: support@datadoghq.com
name: Datadog Support
url: https://www.datadoghq.com/support/
description: The Datadog API is an HTTP REST API. The API uses resource-oriented URLs to call the API, uses status codes to indicate the success or failure of requests, returns JSON from all requests, and uses standard HTTP response codes. Use the Datadog API to access the Datadog platform programmatically.
title: Datadog Account Logs API
version: '1.0'
servers:
- url: https://{subdomain}.{site}
variables:
site:
default: datadoghq.com
description: The regional site for Datadog customers.
enum:
- datadoghq.com
- us3.datadoghq.com
- us5.datadoghq.com
- ap1.datadoghq.com
- datadoghq.eu
- ddog-gov.com
subdomain:
default: api
description: The subdomain where the API is deployed.
- url: '{protocol}://{name}'
variables:
name:
default: api.datadoghq.com
description: Full site DNS name.
protocol:
default: https
description: The protocol for accessing the API.
- url: https://{subdomain}.{site}
variables:
site:
default: datadoghq.com
description: Any Datadog deployment.
subdomain:
default: api
description: The subdomain where the API is deployed.
security:
- apiKeyAuth: []
appKeyAuth: []
tags:
- description: Search your logs and send them to your Datadog platform over HTTP. See the [Log Management page](https://docs.datadoghq.com/logs/) for more information.
name: Logs
paths:
/api/v2/audit/events:
get:
description: 'List endpoint returns events that match a Audit Logs search query.
[Results are paginated][1].
Use this endpoint to see your latest Audit Logs events.
[1]: https://docs.datadoghq.com/logs/guide/collect-multiple-logs-with-pagination'
operationId: ListAuditLogs
parameters:
- description: Search query following Audit Logs syntax.
example: '@type:session @application_id:xxxx'
in: query
name: filter[query]
required: false
schema:
type: string
- description: Minimum timestamp for requested events.
example: '2019-01-02T09:42:36.320Z'
in: query
name: filter[from]
required: false
schema:
format: date-time
type: string
- description: Maximum timestamp for requested events.
example: '2019-01-03T09:42:36.320Z'
in: query
name: filter[to]
required: false
schema:
format: date-time
type: string
- description: Order of events in results.
in: query
name: sort
required: false
schema:
$ref: '#/components/schemas/AuditLogsSort'
example: example_value
- description: List following results with a cursor provided in the previous query.
example: eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ==
in: query
name: page[cursor]
required: false
schema:
type: string
- description: Maximum number of events in the response.
example: 25
in: query
name: page[limit]
required: false
schema:
default: 10
format: int32
maximum: 1000
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AuditLogsEventsResponse'
description: OK
'400':
$ref: '#/components/responses/BadRequestResponse'
'403':
$ref: '#/components/responses/NotAuthorizedResponse'
'429':
$ref: '#/components/responses/TooManyRequestsResponse'
summary: Datadog Get a List of Audit Logs Events
tags:
- Logs
x-menu-order: 2
x-pagination:
cursorParam: page[cursor]
cursorPath: meta.page.after
limitParam: page[limit]
resultsPath: data
x-permission:
operator: OR
permissions:
- audit_logs_read
x-undo:
type: safe
x-api-evangelist-processing:
PascalCaseOperationSummaries: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v2/audit/events/search:
post:
description: 'List endpoint returns Audit Logs events that match an Audit search query.
[Results are paginated][1].
Use this endpoint to build complex Audit Logs events filtering and search.
[1]: https://docs.datadoghq.com/logs/guide/collect-multiple-logs-with-pagination'
operationId: SearchAuditLogs
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AuditLogsSearchEventsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AuditLogsEventsResponse'
description: OK
'400':
$ref: '#/components/responses/BadRequestResponse'
'403':
$ref: '#/components/responses/NotAuthorizedResponse'
'429':
$ref: '#/components/responses/TooManyRequestsResponse'
summary: Datadog Search Audit Logs Events
tags:
- Logs
x-codegen-request-body-name: body
x-menu-order: 1
x-pagination:
cursorParam: body.page.cursor
cursorPath: meta.page.after
limitParam: body.page.limit
resultsPath: data
x-permission:
operator: OR
permissions:
- audit_logs_read
x-undo:
type: safe
x-api-evangelist-processing:
PascalCaseOperationSummaries: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v2/integration/aws/logs/services:
get:
description: Get a list of AWS services that can send logs to Datadog.
operationId: ListAWSLogsServices
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AWSLogsServicesResponse'
description: AWS Logs Services List object
'403':
$ref: '#/components/responses/ForbiddenResponse'
'429':
$ref: '#/components/responses/TooManyRequestsResponse'
summary: Datadog Get List of Aws Log Ready Services
tags:
- Logs
x-menu-order: 1
x-permission:
operator: OR
permissions:
- aws_configuration_read
x-undo:
type: safe
x-unstable: '**Note: This endpoint is in public beta. If you have any feedback,
contact [Datadog support](https://docs.datadoghq.com/help/).**'
x-api-evangelist-processing:
PascalCaseOperationSummaries: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v2/logs:
post:
description: 'Send your logs to your Datadog platform over HTTP. Limits per HTTP request are:
- Maximum content size per payload (uncompressed): 5MB
- Maximum size for a single log: 1MB
- Maximum array size if sending multiple logs in an array: 1000 entries
Any log exceeding 1MB is accepted and truncated by Datadog:
- For a single log request, the API truncates the log at 1MB and returns a 2xx.
- For a multi-logs request, the API processes all logs, truncates only logs larger than 1MB, and returns a 2xx.
Datadog recommends sending your logs compressed.
Add the `Content-Encoding: gzip` header to the request when sending compressed logs.
Log events can be submitted with a timestamp that is up to 18 hours in the past.
The status codes answered by the HTTP API are:
- 202: Accepted: the request has been accepted for processing
- 400: Bad request (likely an issue in the payload formatting)
- 401: Unauthorized (likely a missing API Key)
- 403: Permission issue (likely using an invalid API Key)
- 408: Request Timeout, request should be retried after some time
- 413: Payload too large (batch is above 5MB uncompressed)
- 429: Too Many Requests, request should be retried after some time
- 500: Internal Server Error, the server encountered an unexpected condition that prevented it from fulfilling the request, request should be retried after some time
- 503: Service Unavailable, the server is not ready to handle the request probably because it is overloaded, request should be retried after some time'
operationId: SubmitLog
parameters:
- description: HTTP header used to compress the media-type.
in: header
name: Content-Encoding
required: false
schema:
$ref: '#/components/schemas/ContentEncoding'
example: example_value
- description: Log tags can be passed as query parameters with `text/plain` content type.
example: env:prod,user:my-user
in: query
name: ddtags
required: false
schema:
type: string
requestBody:
content:
application/json:
examples:
multi-json-messages:
description: Pass multiple log objects at once.
summary: Multi JSON Messages
value:
- ddsource: nginx
ddtags: env:staging,version:5.1
hostname: i-012345678
message: 2019-11-19T14:37:58,995 INFO [process.name][20081] Hello
service: payment
- ddsource: nginx
ddtags: env:staging,version:5.1
hostname: i-012345679
message: 2019-11-19T14:37:58,995 INFO [process.name][20081] World
service: payment
simple-json-message:
description: Log attributes can be passed as `key:value` pairs in valid JSON messages.
summary: Simple JSON Message
value:
ddsource: nginx
ddtags: env:staging,version:5.1
hostname: i-012345678
message: 2019-11-19T14:37:58,995 INFO [process.name][20081] Hello World
service: payment
schema:
$ref: '#/components/schemas/HTTPLog'
application/logplex-1:
examples:
multi-raw-message:
description: Submit log messages.
summary: Multi Logplex Messages
value: '2019-11-19T14:37:58,995 INFO [process.name][20081] Hello
2019-11-19T14:37:58,995 INFO [process.name][20081] World'
simple-logplex-message:
description: Submit log string.
summary: Simple Logplex Message
value: 2019-11-19T14:37:58,995 INFO [process.name][20081] Hello World
schema:
type: string
text/plain:
examples:
multi-raw-message:
description: Submit log string.
summary: Multi Raw Messages
value: '2019-11-19T14:37:58,995 INFO [process.name][20081] Hello
2019-11-19T14:37:58,995 INFO [process.name][20081] World
'
simple-raw-message:
description: 'Submit log string. Log attributes can be passed as query parameters in the URL. This enables the addition of tags or the source by using the `ddtags` and `ddsource` parameters: `?host=my-hostname&service=my-service&ddsource=my-source&ddtags=env:prod,user:my-user`.'
summary: Simple Raw Message
value: 2019-11-19T14:37:58,995 INFO [process.name][20081] Hello World
schema:
type: string
description: Log to send (JSON format).
required: true
responses:
'202':
content:
application/json:
schema:
type: object
description: Request accepted for processing (always 202 empty JSON).
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPLogErrors'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPLogErrors'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPLogErrors'
description: Forbidden
'408':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPLogErrors'
description: Request Timeout
'413':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPLogErrors'
description: Payload Too Large
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPLogErrors'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPLogErrors'
description: Internal Server Error
'503':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPLogErrors'
description: Service Unavailable
security:
- apiKeyAuth: []
servers:
- url: https://{subdomain}.{site}
variables:
site:
default: datadoghq.com
description: The regional site for customers.
enum:
- datadoghq.com
- us3.datadoghq.com
- us5.datadoghq.com
- ap1.datadoghq.com
- datadoghq.eu
- ddog-gov.com
subdomain:
default: http-intake.logs
description: The subdomain where the API is deployed.
- url: '{protocol}://{name}'
variables:
name:
default: http-intake.logs.datadoghq.com
description: Full site DNS name.
protocol:
default: https
description: The protocol for accessing the API.
- url: https://{subdomain}.{site}
variables:
site:
default: datadoghq.com
description: Any Datadog deployment.
subdomain:
default: http-intake.logs
description: The subdomain where the API is deployed.
summary: Datadog Send Logs
tags:
- Logs
x-codegen-request-body-name: body
x-menu-order: 1
x-undo:
type: safe
x-api-evangelist-processing:
PascalCaseOperationSummaries: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v2/logs/events:
get:
description: 'List endpoint returns logs that match a log search query.
[Results are paginated][1].
Use this endpoint to search and filter your logs.
**If you are considering archiving logs for your organization,
consider use of the Datadog archive capabilities instead of the log list API.
See [Datadog Logs Archive documentation][2].**
[1]: /logs/guide/collect-multiple-logs-with-pagination
[2]: https://docs.datadoghq.com/logs/archives'
operationId: ListLogsGet
parameters:
- description: Search query following logs syntax.
example: '@datacenter:us @role:db'
in: query
name: filter[query]
required: false
schema:
type: string
- description: 'For customers with multiple indexes, the indexes to search.
Defaults to ''*'' which means all indexes'
example:
- main
- web
explode: false
in: query
name: filter[indexes]
required: false
schema:
items:
description: The name of a log index.
type: string
type: array
- description: Minimum timestamp for requested logs.
example: '2019-01-02T09:42:36.320Z'
in: query
name: filter[from]
required: false
schema:
format: date-time
type: string
- description: Maximum timestamp for requested logs.
example: '2019-01-03T09:42:36.320Z'
in: query
name: filter[to]
required: false
schema:
format: date-time
type: string
- description: Specifies the storage type to be used
example: indexes
in: query
name: filter[storage_tier]
required: false
schema:
$ref: '#/components/schemas/LogsStorageTier'
- description: Order of logs in results.
in: query
name: sort
required: false
schema:
$ref: '#/components/schemas/LogsSort'
example: example_value
- description: List following results with a cursor provided in the previous query.
example: eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ==
in: query
name: page[cursor]
required: false
schema:
type: string
- description: Maximum number of logs in the response.
example: 25
in: query
name: page[limit]
required: false
schema:
default: 10
format: int32
maximum: 1000
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/LogsListResponse'
description: OK
'400':
$ref: '#/components/responses/BadRequestResponse'
'403':
$ref: '#/components/responses/NotAuthorizedResponse'
'429':
$ref: '#/components/responses/TooManyRequestsResponse'
summary: Datadog Search Logs (get)
tags:
- Logs
x-menu-order: 4
x-pagination:
cursorParam: page[cursor]
cursorPath: meta.page.after
limitParam: page[limit]
resultsPath: data
x-permission:
operator: OR
permissions:
- logs_read_data
x-undo:
type: safe
x-api-evangelist-processing:
PascalCaseOperationSummaries: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/v2/logs/events/search:
post:
description: 'List endpoint returns logs that match a log search query.
[Results are paginated][1].
Use this endpoint to search and filter your logs.
**If you are considering archiving logs for your organization,
consider use of the Datadog archive capabilities instead of the log list API.
See [Datadog Logs Archive documentation][2].**
[1]: /logs/guide/collect-multiple-logs-with-pagination
[2]: https://docs.datadoghq.com/logs/archives'
operationId: ListLogs
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LogsListRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/LogsListResponse'
description: OK
'400':
$ref: '#/components/responses/BadRequestResponse'
'403':
$ref: '#/components/responses/NotAuthorizedResponse'
'429':
$ref: '#/components/responses/TooManyRequestsResponse'
summary: Datadog Search Logs (post)
tags:
- Logs
x-codegen-request-body-name: body
x-menu-order: 3
x-pagination:
cursorParam: body.page.cursor
cursorPath: meta.page.after
limitParam: body.page.limit
resultsPath: data
x-permission:
operator: OR
permissions:
- logs_read_data
x-undo:
type: safe
x-api-evangelist-processing:
PascalCaseOperationSummaries: true
ChooseTags: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
AuditLogsResponseLinks:
description: Links attributes.
properties:
next:
description: 'Link for the next set of results. Note that the request can also be made using the
POST endpoint.'
example: https://app.datadoghq.com/api/v2/audit/event?filter[query]=foo&page[cursor]=eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ==
type: string
type: object
LogsAggregateResponseStatus:
description: The status of the response
enum:
- done
- timeout
example: done
type: string
x-enum-varnames:
- DONE
- TIMEOUT
AuditLogsResponseStatus:
description: The status of the response.
enum:
- done
- timeout
example: done
type: string
x-enum-varnames:
- DONE
- TIMEOUT
AuditLogsResponsePage:
description: Paging attributes.
properties:
after:
description: The cursor to use to get the next results, if any. To make the next request, use the same parameters with the addition of `page[cursor]`.
example: eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ==
type: string
type: object
LogsResponseMetadata:
description: The metadata associated with a request
properties:
elapsed:
description: The time elapsed in milliseconds
example: 132
format: int64
type: integer
page:
$ref: '#/components/schemas/LogsResponseMetadataPage'
request_id:
description: The identifier of the request
example: MWlFUjVaWGZTTTZPYzM0VXp1OXU2d3xLSVpEMjZKQ0VKUTI0dEYtM3RSOFVR
type: string
status:
$ref: '#/components/schemas/LogsAggregateResponseStatus'
warnings:
description: 'A list of warnings (non fatal errors) encountered, partial results might be returned if
warnings are present in the response.'
items:
$ref: '#/components/schemas/LogsWarning'
type: array
type: object
AuditLogsWarning:
description: Warning message indicating something that went wrong with the query.
properties:
code:
description: Unique code for this type of warning.
example: unknown_index
type: string
detail:
description: Detailed explanation of this specific warning.
example: 'indexes: foo, bar'
type: string
title:
description: Short human-readable summary of the warning.
example: One or several indexes are missing or invalid, results hold data from the other indexes
type: string
type: object
HTTPLog:
description: Structured log message.
items:
$ref: '#/components/schemas/HTTPLogItem'
type: array
AuditLogsEventAttributes:
description: JSON object containing all event attributes and their associated values.
properties:
attributes:
additionalProperties: {}
description: JSON object of attributes from Audit Logs events.
example:
customAttribute: 123
duration: 2345
type: object
message:
description: Message of the event.
type: string
example: CPU usage is high on {{host.name}}
service:
description: 'Name of the application or service generating Audit Logs events.
This name is used to correlate Audit Logs to APM, so make sure you specify the same
value when you use both products.'
example: web-app
type: string
tags:
description: Array of tags associated with your event.
example:
- team:A
items:
description: Tag associated with your event.
type: string
type: array
timestamp:
description: Timestamp of your event.
example: '2019-01-02T09:42:36.320Z'
format: date-time
type: string
type: object
AWSLogsServicesResponseData:
description: AWS Logs Services response body
properties:
attributes:
$ref: '#/components/schemas/AWSLogsServicesResponseAttributes'
id:
default: logs_services
description: The `AWSLogsServicesResponseData` `id`.
example: logs_services
type: string
type:
$ref: '#/components/schemas/AWSLogsServicesResponseDataType'
required:
- id
- type
type: object
LogAttributes:
description: JSON object containing all log attributes and their associated values.
properties:
attributes:
additionalProperties: {}
description: JSON object of attributes from your log.
example:
customAttribute: 123
duration: 2345
type: object
host:
description: Name of the machine from where the logs are being sent.
example: i-0123
type: string
message:
description: 'The message [reserved attribute](https://docs.datadoghq.com/logs/log_collection/#reserved-attributes)
of your log. By default, Datadog ingests the value of the message attribute as the body of the log entry.
That value is then highlighted and displayed in the Logstream, where it is indexed for full text search.'
example: Host connected to remote
type: string
service:
description: 'The name of the application or service generating the log events.
It is used to switch from Logs to APM, so make sure you define the same
value when you use both products.'
example: agent
type: string
status:
description: Status of the message associated with your log.
example: INFO
type: string
tags:
description: Array of tags associated with your log.
example:
- team:A
items:
description: Tag associated with your log.
type: string
type: array
timestamp:
description: Timestamp of your log.
example: '2019-01-02T09:42:36.320Z'
format: date-time
type: string
type: object
Log:
description: Object description of a log after being processed and stored by Datadog.
properties:
attributes:
$ref: '#/components/schemas/LogAttributes'
id:
description: Unique ID of the Log.
example: AAAAAWgN8Xwgr1vKDQAAAABBV2dOOFh3ZzZobm1mWXJFYTR0OA
type: string
type:
$ref: '#/components/schemas/LogType'
type: object
APIErrorResponse:
description: API error response.
properties:
errors:
description: A list of errors.
example:
- Bad Request
items:
description: A list of items.
example: Bad Request
type: string
type: array
required:
- errors
type: object
AuditLogsQueryFilter:
description: Search and filter query settings.
properties:
from:
default: now-15m
description: Minimum time for the requested events. Supports date, math, and regular timestamps (in milliseconds).
example: now-15m
type: string
query:
default: '*'
description: Search query following the Audit Logs search syntax.
example: '@type:session AND @session.type:user'
type: string
to:
default: now
description: Maximum time for the requested events. Supports date, math, and regular timestamps (in milliseconds).
example: now
type: string
type: object
LogsResponseMetadataPage:
description: Paging attributes.
properties:
after:
description: 'The cursor to use to get the next results, if any. To make the next request, use the same
parameters with the addition of the `page[cursor]`.'
example: eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ==
type: string
type: object
LogType:
default: log
description: Type of the event.
enum:
- log
example: log
type: string
x-enum-varnames:
- LOG
AWSLogsServicesResponseDataType:
default: logs_services
description: The `AWSLogsServicesResponseData` `type`.
enum:
- logs_services
example: logs_services
type: string
x-enum-varnames:
- LOGS_SERVICES
AuditLogsQueryPageOptions:
description: Paging attributes for listing events.
properties:
cursor:
description: List following results with a cursor provided in the previous query.
example: eyJzdGFydEF0IjoiQVFBQUFYS2tMS3pPbm40NGV3QUFBQUJCV0V0clRFdDZVbG8zY3pCRmNsbHJiVmxDWlEifQ==
type: string
limit:
default: 10
description: Maximum number of events in the response.
example: 25
format: int32
maximum: 1000
type: integer
type: object
LogsListResponse:
description: Response object with all logs matching the request and pagination information.
properties:
data:
description: Array of logs matching the request.
items:
$ref: '#/components/schemas/Log'
type: array
links:
$ref: '#/components/schemas/LogsListResponseLinks'
meta:
$ref: '#/components/schemas/LogsResponseMetadata'
type: object
LogsSort:
description: Sort parameters when querying logs.
enum:
- timestamp
- -timestamp
type: string
x-enum-varnames:
- TIMESTAMP_ASCENDING
- TIMESTAMP_DESCENDING
AuditLogsResponseMetadata:
description: The metadata associated with a request.
properties:
elapsed:
description: Time elapsed in milliseconds.
example: 132
format: int64
type: integer
page:
$ref: '#/components/schemas/AuditLogsResponsePage'
request_id:
description: The identifier of the request.
example: MWlFUjVaWGZTTTZPYzM0VXp1OXU2d3xLSVpEMjZKQ0VKUTI0dEYtM3RSOFVR
type: string
status:
$ref: '#/components/schemas/AuditLogsResponseStatus'
warnings:
description: 'A list of warnings (non-fatal errors) encountered. Partial results may return if
warnings are present in the response.'
items:
$ref: '#/components/schemas/AuditLogsWarning'
type: array
type: object
LogsWarning:
description: A warning message indicating something that went wrong with the query
properties:
code:
description: A unique code for this type of warning
example: unknown_index
type: string
detail:
description: A detailed explanation of this specific warning
example: 'indexes: foo, bar'
type: string
title:
description: A short human-readable summary of the warning
example: One or several indexes are missing or invalid, results hold data from the other indexes
type: string
type: object
LogsStorageTier:
default: indexes
description: Specifies storage type as indexes, online-archives or flex
enum:
- indexes
- online-archives
- flex
example: indexes
type: string
x-enum-varnames:
- INDEXES
- ONLINE_ARCHIVES
- FLEX
AuditLogsEventType:
default: audit
description: Type of the event.
enum:
- audit
example: audit
type: string
x-enum-varnames:
- Audit
HTTPLogError:
de
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/datadog/refs/heads/main/openapi/datadog-logs-api-openapi.yml