Ingest business events via API

You can configure external business or IT systems to send business events to Dynatrace via API. Additionally, you can query data using DQL via API. For both API approaches, you need a valid bearer token for authentication, which you request by setting up OAuth for API access.

Latest Dynatrace Business Analytics offers the Business events API to ingest JSON-format data into Dynatrace via the /bizevents/ingest endpoint.
Latest Dynatrace The Grail - DQL Query API enables you to access records stored in Grail by making DQL queries via API.

Set up and use OAuth for API access

Before you begin, you need to set up OAuth for API access.

Create an OAuth client

Create an IAM policy

Bind the policy to a group

Obtain a bearer token

Authenticate

Create an OAuth client

You can create new OAuth clients on the Account Management page of your Dynatrace environment.

From the user menu, select Account settings (previous Dynatrace) or Account Management (latest Dynatrace).

If you have access to multiple Dynatrace environments, be sure to select the correct one.
From the top navigation bar, select Identity & access management > OAuth clients.
Select Create client.
Provide the email address of the user who will own the client.
Provide a description for the new client.
Ensure that your client has the required permissions by selecting one or more options during client setup. For reading and writing business events, you require:
- Read bizevents: (storage:bizevents:read)
- Read buckets: (storage:buckets:read)
- Write/edit events (storage:events:write) (only necessary for ingesting data via the Business events API)
Select Create client.
Save the generated client secret to a password manager for future use. You will also require the generated client ID when obtaining a bearer token.

The client secret is only displayed once upon creation, after which it's stored encrypted and can't be revealed.

Create an IAM policy

To use the OAuth client, you need to ensure that the right IAM policy is assigned to your user.

To set up the policy

From the user menu, select Account settings (previous Dynatrace) or Account Management (latest Dynatrace).

If you have access to multiple Dynatrace environments, be sure to select the correct one.
From the top navigation bar, select Identity & access management > Policies.
Select Create policy and set up the policy name and description. You'll need this information when bind this policy to a user group later. Read more about policy management in Manage IAM policies.

Add the following policy statements for writing and querying business events.

plaintext
ALLOW storage:buckets:read WHERE storage:table-name = "bizevents";
ALLOW storage:bizevents:read;
ALLOW storage:events:write;

Select Create policy.

Bind the policy to a group

You can assign the policy you created to a group that your user belongs to or add your user to a new group. See Manage group permissions with IAM policies for instructions on binding policies to groups.

Obtain a bearer token

You can use the OAuth client to obtain an OAuth 2.0 bearer token. Use the information below send a request to the bearer token URL. Use the token you receive in the response to authenticate to the Business events API or the Grail - DQL Query API.

Endpoint URL for requesting a token—https://sso.dynatrace.com/sso/oauth2/token
Method—POST
Content-Type header—application/x-www-form-urlencoded

Headers—You can send the following keys or parameters in the request body. Make sure to URL encode all values.

Key/Parameter	Value	Required
`grant_type`	`client_credentials`	required
`client_id`	`dt0s02.****`—This is the client ID generated when you created an OAuth client.	required
`client_secret`	`dt0s02.*.**`—This is the client secret generated when you created an OAuth client.	required
`scope`	A list of required scopes separated by a whitespace, for example, `storage:bizevents:read storage:buckets:read storage:events:write` You can assign multiple scopes to a single token, or you can generate several tokens, each with different access levels and use them accordingly—check your organization's security policies for the best practice.	required
`resource`	`urn:dtaccount:{your-account-UUID}`	optional if not defined in the client required if defined in the client, with the same value as in the client

Example API request

Request headers

plaintext
POST /sso/oauth2/token HTTP/2

Host: sso.dynatrace.com

content-type: application/x-www-form-urlencoded

Request body

plaintext
grant_type=client_credentials&client_id=dt0s02.****&client_secret=dt0s02.***.****&scope=storage%3Abizevents%3Aread+storage%3Aevents%3Awrite+storage%3Abuckets%3Aread

Example API response

plaintext
{

   "scope": "storage:bizevents:read storage:events:write storage:buckets:read",

   "token_type":"Bearer",

   "expires_in":300,

   "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjEifQ.eyJzdWIiOiI2YWUwMmFmNC01NmIwLTRhM2MtODI0OS1mYjc2ZDgyOTYwYTQiLCJyZXMiOiJ1cm46ZHRhY2NvdW50OjJiMjM2NDM4LTJhMzEtNDg3Mi04NjU1LWJjYTRmYThhZjkxNyIsIl9jbGFpbV9uYW1lcyI6eyJncm91cHMiOiIwIn0sInByZWZlcnJlZF91c2VybmFtZSI6ImRhbmllbC5tYXJzY2huaWdAZHluYXRyYWNlLmNvbSIsImd0IjoiY2MiLCJpbnQiOnRydWUsImF1ZCI6ImR0MHMwMi4zWkJZWkhWVCIsInNjb3BlIjoiYWNjb3VudC1pZG0tcmVhZCBhY2NvdW50LWlkbS13cml0ZSBhY2NvdW50LWVudi1yZWFkIGFjY291bnQtZW52LXdyaXRlIGFjY291bnQtdWFjLXJlYWQgYWNjb3VudC11YWMtd3JpdGUgaWFtLXBvbGljaWVzLW1hbmFnZW1lbnQgaWFtOnBvbGljaWVzOndyaXRlIGlhbTpwb2xpY2llczpyZWFkIGlhbTpiaW5kaW5nczp3cml0ZSBpYW06YmluZGluZ3M6cmVhZCBpYW06ZWZmZWN0aXZlLXBlcm1pc3Npb25zOnJlYWQgc3RvcmFnZTpiaXpldmVudHM6cmVhZCBzdG9yYWdlOmV2ZW50czp3cml0ZSIsIl9jbGFpbV9zb3VyY2VzIjp7IjAiOnsiZW5kcG9pbnQiOm51bGx9fSwiZXhwIjoxNjkxNjE1NTcxLCJpYXQiOjE2OTE2MTUyNzEsImp0aSI6ImJmNDZhNmFhLTRjZmItNDA1MS05ZmUzLTMzZTljMjc0OTdhZSIsImVtYWlsIjoiZGFuaWVsLm1hcnNjaG5pZ0BkeW5hdHJhY2UuY29tIn0.x3_dUuOmdqcrrsfuRyiUwKOOFSJ30fAQnpKGbJTNGy8N3qspKDO0OC36Z0GILc275bTsLY3fARzRQNBOW1Okmg",

   "resource":"urn:dtaccount:2b236438-2a31-4872-8655-bca4fa8af917"

}

Authenticate

To authenticate a call, attach the token to the Authorization HTTP header preceding the Bearer realm.

plaintext
--header 'Authorization: Bearer abcdefjhij1234567890'

Business events API: `/bizevents/ingest` endpoint

Latest Dynatrace Business Analytics offers the Business events API to ingest JSON data into Dynatrace via the POST method of the /bizevents/ingest endpoint.

To view Swagger documentation and try out this API in the latest Dynatrace

Search for "API" or "Dynatrace API."
From the dropdown list in the top-right corner of the page, select Classic Environment API v2.
Expand Business events, then /bizevents/ingest.

In the previous Dynatrace

From the user menu, select Environment API v2.
Expand Business events, then /bizevents/ingest.

Endpoint URL
- Latest Dynatrace https://{your-environment-id}.apps.dynatrace.com/platform/classic/environment-api/v2/bizevents/ingest
- Previous Dynatrace https://{your-environment-id}.live.dynatrace.com/api/v2/bizevents/ingest
Method—POST
Authentication—OAuth
Content-Type header—varies based on the payload format.
- Pure JSON: application/json
- CloudEvents: application/cloudevent+json
- CloudEvents batch: application/cloudevent-batch+json
Request body—{your event}—see the examples below.

Note that when ingesting business events, Dynatrace stores ingested top-level fields as top-level fields in Grail but converts complex JSON objects into strings—see the customer field in the example Grail event below.

Supported request formats and examples

In addition to the pure JSON format, Dynatrace offers the CloudEvents and CloudEvents batch payload formats, specified in the Content-Type request header.

All three formats support the same request payloads. The Business events API limits payload size to 1 MB per request.

Pure JSON

There are no mandatory fields.

Example payload in pure JSON for ingesting a single event

json
{
   "id":"2",
   "paymentType":"paypal",
   "plannedDeliveryDate":"01.01.2024",
   "event.type":"com.bizevent.single",
   "event.provider":"custom.provider",
   "total":234,
   "customer":{
      "firstName":"John",
      "lastName":"Doe"
   },
   "orderItemsProductIDs":[
      "PR-102002002",
      "QZ-123232"
   ]
}

How Grail stores the single event

Every top-level attribute is stored as a top-level field in Grail; nested JSON objects are stored as strings.

json
{
   "timestamp":"2023-08-10T10:06:21.697000000+02:00",
   "customer":"{\"firstName\":\"John\",\"lastName\":\"Doe\"}",
   "event.id":"6f7c0c12-8386-4015-bcb2-296ba73ebd54",
   "event.kind":"BIZ_EVENT",
   "event.provider":"custom.provider",
   "event.type":"com.bizevent.single",
   "id":"2",
   "orderItemsProductIDs":"[\"PR-102002002\",\"QZ-123232\"]",
   "paymentType":"paypal",
   "plannedDeliveryDate":"01.01.2024",
   "total":234
}

Example payload in pure JSON for ingesting multiple events

json
[
   {
      "id":"1",
      "paymentType":"paypal",
      "plannedDeliveryDate":"01.01.2021",
      "event.provider":"custom.provider.array",
      "total":234,
      "customer":{
         "firstName":"John",
         "lastName":"Doe"
      },
      "orderItemsProductIDs":[
         "PR-102002002",
         "QZ-123232"
      ]
   },
   {
      "id":"1",
      "paymentType":"paypal",
      "plannedDeliveryDate":"01.01.2021",
      "event.provider":"custom.provider.array",
      "total":234,
      "customer":{
         "firstName":"John",
         "lastName":"Doe"
      },
      "orderItemsProductIDs":[
         "PR-102002002",
         "QZ-123232"
      ]
   }
]

CloudEvents

In the CloudEvents standard, these required fields can be enriched by additional data fields.

specversion
source—Automatically converted to event.provider
type—Automatically converted to event.type
id—Automatically converted to event.id

Provide additional data in the data object fields. In the example below, the additional data is paymentId, orderId, and person.

Example CloudEvents payload

json
{
  "specversion": "1.0",
  "id": "8d8c6e5d-829d-4629-86fb-23cda5496fa9",
  "source": "ba.dt.local",
  "type": "com.dynatrace.business",
  "time": "2023-08-07T07:07:13.532Z",
  "data": {
    "paymentId": "110",
    "orderId": "5117",
    "person": {
      "firstName": "Max",
      "lastName": "Meyer"
    }
  }
}

CloudEvents batch

The CloudEvents batch mode enables the ingestion of multiple events at a time. As in the previous example, required fields can be enriched by additional data fields, such as paymentId and orderId.

Example CloudEvents batch payload

json
[
  {
    "specversion": "1.0",
    "id": "8d8c6e5d-829d-4629-86fb-23cda5496fa9",
    "source": "ba.dt.local",
    "type": "com.dynatrace.business",
    "time": "2023-08-07T07:07:13.532Z",
    "data": {
      "paymentId": "110",
      "orderId": "5717"
    }
  },
  {
    "specversion": "1.0",
    "id": "37d9df29-ba57-4526-8ac7-6baa6ccbc9c4",
    "source": "ba.dt.local",
    "type": "com.dynatrace.business",
    "time": "2023-08-07T07:07:14.532Z",
    "data": {
      "paymentId": "111",
      "orderId": "5718"
    }
  }
]

Business event enrichment

When you report business events, Dynatrace enriches them by adding more context. For example, Dynatrace adds information about your application, geolocation, device, and more. Pertains only data ingested via Business events API.

For details, see Business event enrichment.

DQL queries via API

Latest Dynatrace The Dynatrace Grail - DQL Query API enables third-party applications to retrieve data from Grail by executing DQL queries via API. You can only query data, not ingest it via this API.

To view Swagger documentation and try out this API in the latest Dynatrace

Search for "API" or "Dynatrace API."
From the dropdown list in the top-right corner of the page, select Grail - DQL Query.
Expand Query Execution to view its methods.

To run a query and to retrieve its result, you need to make two requests via separate methods.

To query Grail, execute the POST /query:execute request.
To retrieve the result, execute the GET /query:poll request.

POST /query:execute method

Endpoint URL—https://{your-environment-id}.apps.dynatrace.com/platform/storage/query/v1/query:execute
Method—POST
Authentication—OAuth
Content-Type header—application/json
Request body—{your DQL query}

Request body example

json
{
  "query": "fetch bizevents | summarize Count()"
}

Response body example

You will need to use the requestToken value from this response in the /query:poll request.

json
{
  "state": "SUCCEEDED",
  "requestToken": " +kuSj8qvRvq64GkG5CEHag==",
  "progress": 100
}

GET /query:poll method

Endpoint URL—https://{your-environment-id}.apps.dynatrace.com/platform/storage/query/v1/query:poll
Method—GET
Authentication—OAuth
Content-Type header—application/json (Pure JSON)
GET parameter—request-token, used to identify the executed POST query

Request URL example

plaintext
https://mySampleEnv.apps.dynatrace.com/platform/storage/query/v1/query:poll?request-token=%2BkuSj8qvRvq64GkG5CEHag%3D%3D

Response body example

json
{
  "state": "SUCCEEDED",
  "progress": 100,
  "result": {
    "records": [
      {
        "count()": "0"
      }
    ],
    "types": [
      {
        "indexRange": [
          0,
          0
        ],
        "mappings": {
          "count()": {
            "type": "long"
          }
        }
      }
    ],
    "metadata": {
      "grail": {
        "canonicalQuery": "fetch bizevents\n| summarize count()",
        "timezone": "Z",
        "query": "fetch bizevents | summarize Count()",
        "scannedRecords": 0,
        "dqlVersion": "V1_0",
        "scannedBytes": 0,
        "analysisTimeframe": {
          "start": "2023-07-11T07:28:11.068767000Z",
          "end": "2023-07-11T09:28:11.068767000Z"
        },
        "locale": "",
        "executionTimeMilliseconds": 4155,
        "notifications": [],
        "queryId": "fa4b928f-caaf-46fa-bae0-6906e421076a",
        "sampled": false
      }
    }
  }
}

Ingest business events via API

Set up and use OAuth for API access

Create an OAuth client

Create an IAM policy

Bind the policy to a group

Obtain a bearer token

Authenticate

Business events API: /bizevents/ingest endpoint

Supported request formats and examples

Business event enrichment

DQL queries via API

POST /query:execute method

Request body example

Response body example

GET /query:poll method

Request URL example

Response body example

Business events API: `/bizevents/ingest` endpoint