Exporting events programmatically using the V2 API

From an IBM Cloud Activity Tracker instance, you can export events programmatically by using the V2 Export REST API.

As of 28 March 2024 the IBM Log Analysis and IBM Cloud Activity Tracker services are deprecated and will no longer be supported as of 30 March 2025. Customers will need to migrate to IBM Cloud Logs, which replaces these two services, prior to 30 March 2025. For information about IBM Cloud Logs, see the IBM Cloud Logs documentation.

The V2 Export REST API does not support sending the events by email. If you need email support, you will need to use the V1 Export REST API.

Consider the following information when you export event data:

You export a set of event entries. To define the set of data that you want to export, you can apply filter and searches. You can also specify the time range.
The compressed event file that contains the data that you want to export is available for a maximum of 12 hours.
When you export events, you have a limit of lines that you can export in a request. You can specify to export older lines or newer lines in case you reach the limit in the time range that you specify for the export. The maximum number of lines that you can export per page is 10,000 lines with no limit on the number of pages.

The number of concurrent export request is limited depending on your service plan.

Limits of concurrent export requests
Plan	Limit
7 days log search	1
14 days log search	1
30 days log search	2
HIPPA 30 days log search	2

Prerequisites

To export events, consider the following information:

You must have a paid service plan for the IBM Cloud Activity Tracker service. Learn more.
Check that your user ID has permissions to launch the web UI, view or manage service keys, and view events. Learn more.
Check that the auditing instance has the export feature enabled. Learn more.

Export API

Use ENDPOINT/v2/export?QUERY_PARAMETERS" -u SERVICE_KEY: to export events.

ENDPOINT represents the entry point to the service. Each region has a different URL. To export events from a auditing instance, see Endpoints.

QUERY_PARAMETERS are parameters that define the filtering criteria that is applied to the export request.

SERVICE_KEY is an API key that you must use to validate your credentials with the auditing instance. For more information on how to get a service key, see Service keys by using the API.

The : after SERVICE_KEY is required.

Query parameters

You can define query parameters to refine the events that you want to export.

The following table lists the query parameters that you can set:

Query parameters
Query parameter	Type	Status	Description
`from`	`int32`	Required	Start time. Set as UNIX timestamp in seconds or milliseconds.
`to`	`int32`	Required	End time. Set as UNIX timestamp in seconds or milliseconds.
`size`	`string`	Optional	Number of event lines to include in the export.
`hosts`	`string`	Optional	Comma-separated list of services. To get the value that you can set for a specific service, you can check the label `Source` in an event that is generated by the service.
`apps`	`string`	Optional	Comma-separated list of service instances represented as CRNs. To get the value that you can set for a specific service, you can check the label `App` in an event that is generated by the service.
`levels`	`string`	Optional	Comma-separated list of severities. Use this field to set the severity of the events that you want to export.
`query`	`string`	Optional	Search query. You can test your query in a view in the UI. Then, when you copy the query to use for the export, replace each blank space in the query with `%20`.
`prefer`	`string`	Optional	Defines the log lines that you want to export. Valid values are `head`, first log lines, and `tail`, last log lines. If not specified, defaults to `tail`.
`pagination_id`	`string`	Optional	Indicates which page of results is retrieved from an export. For the initial export request, this parameter should be omitted. Subsequent requests for pagination should provide the token sent in the response to this parameter.

For example, you can define a set of parameters to include information:

ENDPOINT/v2/export?to=START_TIME&from=END_TIME&hosts=LIST_OF_HOSTS&levels=LIST_OF_LEVELS&size=N&query=(SEARCH_QUERY)" -u $TOKEN:

Exporting events

Complete the following steps to export events programmatically:

Step 1. Get a service key

Get a service key.

Step 2. Identify the data to pass through the export parameters

To verify that the query that you use in the export returns the set of events that you are looking for, define the search query through the UI. Refine the query until you can only see the events that you want to export. Then, map the data to the query parameters.

When you copy the query from the UI, you must replace every space with %20.

Step 3. Map the data to the query parameters

To define the parameters that you need for the export request, complete the following steps:

Map your sources to the hosts parameter. The hosts parameter is a comma-separated list of services.
Map the severity to the levels parameter. The levels parameter is a comma-separated list of severity values.

Map the query to the query parameter.

Notice that when you copy the query from the UI, you must replace every space with %20, every [ with %5B, and every ] with %5D.

For example, if the query from the UI is:

action:iam-groups.group.create OR action:iam-groups.group.delete OR action:iam-groups.group.update OR action:iam-identity.account-profile.create OR action:iam-identity.account-profile.delete OR action:iam-identity.account-profile.update OR action:iam-am.policy.create OR action:iam-am.policy.delete OR action:iam-am.policy.update

You would specify the query as this in the API:

action:iam-groups.group.create%20OR%20action:iam-groups.group.delete%20OR%20action:iam-groups.group.update%20OR%20action:iam-identity.account-profile.create%20OR%20action:iam-identity.account-profile.delete%20OR%20action:iam-identity.account-profile.update%20OR%20action:iam-am.policy.create%20OR%20action:iam-am.policy.delete%20OR%20action:iam-am.policy.update

For this query from the UI:

"q": "action:[iam-groups.group.create.iam-groups.group.delete,iam-groups.group.update,iam-identity.account-profile.create,iam-identity.account-profile.delete,iam-identity.account-profile.update,iam-am.policy.create,iam-am.policy.delete,iam-am.policy.update]"

You would run the following command:

curl -XGET  'https://api.eu-de.logging.cloud.ibm.com/v2/export?from=1690365540000&to=1690451940000&hosts=iam-identity,iam-groups,iam-am&query=action:%5Biam-groups.group.create,iam-groups.group.delete,iam-groups.group.update,iam-identity.account-profile.create,iam-identity.account-profile.delete,iam-identity.account-profile.update,iam-am.policy.create,iam-am.policy.delete,iam-am.policy.update%5D' --header 'servicekey:     xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Step 4. Export the events

Run the following cURL command to export events:

curl "ENDPOINT/v2/export?QUERY_PARAMETERS" -u SERVICE_KEY:

Where

ENDPOINT represents the entry point to the service. Each region has a different URL. Learn more.
QUERY_PARAMETERS are parameters that define the filtering criteria that is applied to the export request.
SERVICE_KEY is the service key that you created in the previous step.

Samples

For example, to write event lines into the terminal, you can run the following command:

curl "https://api.us-south.logging.cloud.ibm.com/v2/export?to=$(date +%s)000&from=$(($(date +%s)-86400))000&levels=info" -u e08c0c759663491880b0d61712346789:

To use the query parameter to find all event lines with a level of info, you can run the following command:

curl -s "https://api.us-south.logging.cloud.ibm.com/v2/export?query=test_query&levels=info" -u :