API event record field reference

Reference table and examples of the data that is stored in an API event record.

When a user calls one of your published APIs, the gateway that processes the API call creates an API event record. Each API event record contains details of the API call such as the application ID, current time, result code, etc. Table 1 shows all the data that can be contained in an API event record.

Activity log settings

The contents of API event records depends on the activity log setting for each API. To find out more about activity logging, see Customize your analytics data.

Important: The maximum API event record size is 19 Mb. The analytics subsystem rejects any API event records that are larger than 19 Mb.

API event record fields

Table 1. API event record fields
Field name Type Description
@timestamp Date A timestamp that records when the Logstash data collection engine (which feeds data into OpenSearch) wrote the record.
api_id String The API identifier.
api_name String The name of the API.
api_resource_id String Field format is: api_name:api_version:method:path. Only available on API Gateway v10.5.3 or higher.
api_version String The version number of the API.
app_id String The identifier for the registered application.
app_name String The name of the registered application.
Note: The property is set to undefined when a client ID is not used or is invalid on the API. The gateway needs a client ID to determine which app was invoking the API. From this app, the gateway can determine what plan the app is subscribed to on the product that contains the API. Without a client ID, the gateway is unable to determine what plan, product, or app was invoked, because a single API can belong to multiple products (each of which have multiple plans and apps that are subscribed to those plans with client IDs).
app_type String The application type, with a value of Production or Development.
bytes_received Number The number of bytes received from the consumer in the request.
bytes_sent Number The number of bytes sent to the consumer in the response.
client_geoip.area_code Number The public switched telephone network (PSTN) area code of the client, as identified from its IP address.
client_geoip.asn Number Autonomous system number of client IP address.
client_geoip.as_org String  
client_geoip.city_name String The city name of the client, as identified from its IP address.
client_geoip.continent_name String The continent name of the client, as identified from its IP address.
client_geoip.continent_code String The two-letter continent code of the client, as identified from its IP address.
client_geoip.country_code2 String The two-letter country code of the client, as identified from its IP address.
client_geoip.country_code3 String The three-letter country code of the client, as identified from its IP address.
client_geoip.country_name String The country name of the client, as identified from its IP address.
client_geoip.dma_code Number The Designated Market Area (DMA) code of the client, as identified from its IP address.
client_geoip.domain String The domain of the client IP address.
client_geoip.ip String The IP address of the client.
client_geoip.isp String The internet service provider of the client.
client_geoip.latitude Number The latitude of the client location, as identified from its IP address.
client_geoip.location String The longitude and latitude of the client location (separated by a comma), as identified from its IP address.
client_geoip.location.lat Number The latitude of the client location, as identified from its IP address.
client_geoip.location.long Number The longitude of the client location, as identified from its IP address.
client_geoip.longitude Number The longitude of the client location, as identified from its IP address.
client_geoip.organization String The client's organization, as identified from its IP address.
client_geoip.postal_code String The postal code of the client, as identified from its IP address.
client_geoip.region_iso_code String The ISO code of the client's region, as identified from its IP address.
client_geoip.region_name String The abbreviated form of the region that corresponds to the IP address of the client.
client_geoip.timezone String The time zone of the client, as identified from its IP address.
client_id String The unique ID of the client that is attached to the API request.
custom_data Array map Custom data can be added to this field.
datetime Date A timestamp that records when the API was invoked. The timestamp is always shown in Coordinated Universal Time.
developer_org_id String The identifier for the consumer organization that owns the application.
developer_org_name String The name of the consumer organization that owns the application.
endpoint_url String When the request failed, endpoint_url identifies the proxy or invoke target URL on which the request failed. It is not included with a successful request. On V5 compatible gateway, this field is only populated when the backend server URL that was invoked returns an HTTP 404 code.
env_id String The catalog identifier.
env_name String The name of the catalog.
event_id String Unique ID assigned to the event by the gateway.

Generated based on a hashed version of the datetime, transaction_id, and client_id fields combined by using the SHA1 algorithm.
gateway_geoip.area_code Number The public switched telephone network (PSTN) area code of the gateway, as identified from its IP address.
gateway_geoip.asn Number Autonomous system number of client IP address.
gateway_geoip.as_org String  
gateway_geoip.city_name String The city name of the gateway, as identified from its IP address.
gateway_geoip.continent_code String The two-letter continent code of the gateway, as identified from its IP address.
gateway_geoip.continent_name String The continent name of the gateway, as identified from its IP address.
gateway_geoip.country_code2 String The two-letter country code of the gateway, as identified from its IP address.
gateway_geoip.country_code3 String The three-letter country code of the gateway, as identified from its IP address.
gateway_geoip.country_name String The country name of the gateway, as identified from its IP address.
gateway_geoip.dma_code Number The Designated Market Area (DMA) code of the gateway, as identified from its IP address.
gateway_geoip.domain String The domain of the gateway IP address.
gateway_geoip.ip String The IP address of the gateway.
gateway_geoip.isp String The internet service provider of the gateway.
gateway_geoip.latitude Number The latitude of the gateway location, as identified from its IP address.
gateway_geoip.location String The longitude and latitude of the gateway location (separated by a comma), as identified from its IP address.
gateway_geoip.location.lat Number The latitude of the gateway location, as identified from its IP address.
gateway_geoip.location.long Number The longitude of the gateway location, as identified from its IP address.
gateway_geoip.longitude Number The longitude of the gateway location, as identified from its IP address.
gateway_geoip.organization String The gateway's organization, as identified from its IP address.
gateway_geoip.postal_code String The postal code of the gateway, as identified from its IP address.
gateway_geoip.region_name String The abbreviated form of the region that corresponds to the IP address of the gateway.
gateway_geoip.region_iso_code String The ISO code of the gateway's region, as identified from its IP address.
gateway_geoip.timezone String The time zone of the gateway, as identified from its IP address.
gateway_ip String The IP address of the gateway.
gateway_service_name String The name of the DataPower API gateway service. Configured by the cloud admin user when registering the gateway service. Only available on DataPower API Gateway v10.5.3 or higher.
gateway_type String The type and version of the gateway that processed the call, in format: type/version. Set by all gateway types except for v5c, and only available on v10.0.8.0 or higher.
global_transaction_id String The DataPower global transaction ID. See https://www.ibm.com/docs/en/datapower-gateway/latest?topic=variables-varserviceglobal-transaction-id-servicevarsglobaltransactionid.
graphql_request_field_cost Number GraphQL APIs only. The maximum cost of all fields accessed in the query. The cost of each field access is configured in the schema.
graphql_request_max_nesting Number GraphQL APIs only. The maximum nesting depth found in the query by the assembly validate action. The schema configuration is used to determine which types are nested, so this value might be less than the nesting depth found by the assembly parse action.
graphql_request_top_field_counts Object GraphQL APIs only. The maximum number of times that a query can retrieve each field. This number is equal to the number of times that the resolver is required to run.

This field is stored in JSON format and is not indexed, so it is not available for visualizations. A limited number of query requests and responses are stored for each entry, based on the amount of data that each contains. The maximum amount of data that can be stored is subject to change.
graphql_request_top_type_counts Object GraphQL APIs only. The maximum number of times that a query can retrieve an object of each type.

This field is stored in JSON format and is not indexed, so it is not available for visualizations. A limited number of query requests and responses are stored for each entry, based on the amount of data that each contains. The maximum amount of data that can be stored is subject to change.
graphql_request_type_cost Number GraphQL APIs only. The maximum cost of all types retrieved in the query. The cost of each type is configured in the schema.
graphql_response_field_cost Number GraphQL APIs only. The cost of all fields accessed in the query. The cost of each field access is configured in the schema.
graphql_response_max_nesting Number GraphQL APIs only. The nesting depth found in the query by the assembly validate action. The schema configuration is used to determine which types are considered nested, so this value might be less than the nesting depth found by the assembly parse action.
graphql_response_top_field_counts Object GraphQL APIs only. The number of times that each field was retrieved by the query. This number is equal to the number of times that the resolver is required to run.

This field is stored in JSON format and is not indexed, so it is not available for visualizations. A limited number of query requests and responses are stored for each entry, based on the amount of data that each contains. The maximum amount of data that can be stored is subject to change.
graphql_response_top_type_counts Object GraphQL APIs only. The number of times that an object of each type was retrieved by the query.

This field is stored in JSON format and is not indexed, so it is not available for visualizations. A limited number of query requests and responses are stored for each entry, based on the amount of data that each contains. The maximum amount of data that can be stored is subject to change.
graphql_response_type_cost Number GraphQL APIs only. The cost of all types that were retrieved in the query. The cost of each type is configured in the schema.
headers.field_name String Internal information that is related to analytics ingestion. headers.field_name is not related to the API call or its response, see request_http_headers for that information.
host String The hostname or IP address of the ingestion node that received the API event.
http_user_agent String The value of the User Agent header on the inbound request.
immediate_client_ip String The client IP address that is directly in front of the gateway. Usually immediate_client_ip is the IP of a load balancer.
latency_info.started Number The time delay (in milliseconds) between when the request was received and when the gateway started the corresponding task. Starting a task comprises multiple steps to prepare for executing an API; for example, completing the TCP/TLS handshake, verifying an app's client ID and secret, and matching the request URI to a catalog, API, and Plan. When the gateway receives a request, the "Start" duration is set to 0. The duration of each step within the Start task is then added up, and the total represents the duration of the Start task.
latency_info.task String The API transaction that was processed.
log_policy String The defined logging policy. Values include none, event, headers, and payload.
org_id String The identifier for the provider organization that owns the API and associated Products.
org_name String The name of the provider organization that owns the API and associated Products.
plan_id String The Plan identifier.
plan_name String The name of the Plan.
Note: The property is set to undefined when a client ID is not used or is invalid on the API. The gateway needs a client id to determine which app was invoking the API. From this app, the gateway can determine what plan the app is subscribed to on the product that contains the API. Without a client ID, the gateway is unable to determine what plan, product, or app was invoked because a single API can belong to multiple products (each of which have multiple plans and apps that are subscribed to those plans with client IDs).
plan_version String The version number of the Plan.
product_name String The Product name.
Note: The property is set to undefined when a client ID is not used or is invalid on the API. The gateway needs a client ID to determine which app was invoking the API. From this app, the gateway can determine what plan the app is subscribed to on the product that contains the API. Without a client ID, the gateway is unable to determine what plan, product, or app wasinvoked because a single API can belong to multiple products (each of which have multiple plans and apps that are subscribed to those plans with client IDs).
product_title String The title of the Product.
product_version String The version number of the Product.
query_string String The URL query string value on the inbound request.
rate_limit.count Number The number of API calls remaining in the specified rate limit time window.
rate_limit.interval Number The total time window during which a certain number of API calls are allowed.
rate_limit.limit Number The maximum number of requests an application is allowed to make to the API during a specified time window.
rate_limit.period Number The time window that is used to set a rate limit for API calls.
rate_limit.reject String An indication of whether calls that exceed the specified rate limit are rejected. If true, the API call is rejected with a 429 status code. If false, a record is created in the Activity log.
rate_limit.shared String An indication of whether the rate limit is shared at a Plan level by all operations, or whether a rate limit is specified on indivIDual operations.
rate_limit.unit Number The time unit used for calculating the rate limit.
Note: Allowed values are second, minute, hour, day, and week
request_body String The body of the inbound request.
request_http_headers.field_name String A component of the HTTP header section of the inbound request; for example, the acceptable encodings, the identification string for the user agent, or the proxies through which the request was sent.
Note: The following types of headers are considered sensitive and do not show in analytics data for security reasons:
  • Any secret key configured in the API security
  • Any header that contains secret
  • Any header that contains Authorization
request_method String The method of the inbound request.
request_protocol String The protocol of the inbound request.
resource String The name of the operation.
resource_id String The operation identifier.
resource_path String The operation path.
response_body String The body of the outbound response.
response_http_headers.field_name String A component of the HTTP header section of the outbound response; for example, the MIME type of the content or the data and time when the message was sent.
scope String Not used for DataPower® API Gateway or DataPower Gateway.
status_code String The status code set on the outbound response.
time_to_serve_request Number The time elapsed (in milliseconds) from when the gateway received the request to when it sent a response.
transaction_id String The identifier for the API transaction. See https://www.ibm.com/docs/en/datapower-gateway/latest?topic=variables-varservicetransaction-id-servicevarstransactionid.
uri_path String The URI path on the inbound request.
user_agent Object The parsed contents of the http_user_agent field, which contains information about the user that made the API call.
user_agent.device String Device name.
user_agent.major String User agent major version number.
user_agent.minor String User agent minor version number.
user_agent.name String User agent name.
user_agent.os_full String Detected operating system full name.
user_agent.os_major String Detected operating system major version number.
user_agent.os_minor String Detected operating system minor version number.
user_agent.os_name String Detected operating system name.
user_agent.os_patch String Detected operating system patch version.
user_agent.os_version String Detected operating system version.
user_agent.patch String User agent patch version.
user_agent.version String Detected user agent version.
Note:

To ensure the value in the client_geoip field is accurate, the gateway must receive the X-Forwarded-For header in all API calls. Check with the administrator of your deployment environment to ensure that the X-Forwarded-For header is passed to your gateways. For example, in a Kubernetes environment where NINGX ingresses are used, configure the NGINX ingress that is used by your gateway to use the X-Forwarded-For header: NGINX Configuration "use-forwarded-headers".

The geoIP feature is useful with internet routable IP addresses only. For instance, 192.168.x.x and 10.x.x.x IP addresses, being internal private IP addresses, cannot be resolved to a geographical location.

Example API event record with payload logging set

{
  "@timestamp": "2024-03-11T12:30:09.105518124Z",
  "@version": "1",
  "api_id": "5973f48d-ee38-406f-bdea-5f04fa4b8dd8",
  "api_name": "p-2-p-bank-apis-api",
  "api_ref": "p-2-p-bank-apis-api:1.0.0",
  "api_version": "1.0.0",
    "app_id": "fd58ef46-de01-4d97-84b3-a2a536270224",
  "app_name": "API Connect App 4",
  "app_type": "production",
  "billing": {
    "amount": 0,
    "currency": "USD",
    "model": "free",
    "provider": "none",
    "trial_period_days": 0
  },
  "bytes_received": "4921",
  "bytes_sent": "4762",
  "catalog_id": "7ae861d0-f138-494e-898b-302ee981a03d",
  "catalog_name": "api-connect-catalog-1",
  "client_geoip": {
        "continent_code": "AS",
    "country_code2": "CN",
    "country_code3": "CN",
    "country_name": "China",
    "ip": "106.27.171.34",
    "latitude": 28.1783,
    "location": {
      "lat": 28.1783,
      "lon": 113.1117
    },
    "longitude": 113.1117,
    "region_code": "HN",
    "region_name": "Hunan",
    "timezone": "Asia/Shanghai"
  },
  "client_id": "8f7e3acb3e1da7d97e243635e03ede6a",
  "client_ip": "106.27.171.34",
  "datetime": "2024-03-11T11:12:36.387Z",
  "debug": [],
  "developer_org_id": "1ab7c606-23ff-40ec-9613-17804ef84c68",
  "developer_org_name": "api-connect-schowalter-abernathy-and-wehner-handmade-practical-cotton-chips-consumer-organization",
  "developer_org_title": "API Connect Schowalter, Abernathy and Wehner - Handmade Practical Cotton Chips Consumer Organization",
  "endpoint_url": "N/A",
  "event_id": "0cf32181471ac5078fef486d21745278df2de4a1",
  "gateway_geoip": {
    "ip": "9.79.12.126",
    "country_code2": "US",
    "country_code3": "USA",
    "country_name": "United States",
    "continent_code": "NA",
    "city_name": "Durham",
    "postal_code": "27709",
    "latitude": 35.994,
    "longitude": -78.8986,
    "dma_code": 560,
    "area_code": 919,
    "timezone": "America/New_York",
        "region_name": "North Carolina",
    "location": {
      "lat": 35.994,
      "long": -78.8986
    }
  },
  "gateway_ip": "192.168.141.185",
  "host": "192.168.46.74",
  "http_user_agent": "Mozilla/5.0 (Linux; Android 8.1.0; SAMSUNG SM-G610M) AppleWebKit/537.36 (KHTML, like Gecko) SamsungBrowser/23.0 Chrome/115.0.0.0 Mobile Safari/537.36",
  "immediate_client_ip": "8.46.111.156",
  "latency_info": [
    {
      "started": 0,
      "task": "Start"
    },
    {
      "started": 18,
      "task": "security-appID"
    },
    {
      "started": 19,
      "task": "PlanRateLimits"
    },
    {
      "started": 20,
      "task": "invoke"
    }
  ],
  "log_policy": "payload",
  "offload_max_queue": -1,
  "offload_queue_size": -1,
  "org_id": "c883b05a-82ca-45f2-a9d9-4696a22d9908",
  "org_name": "boborg",
  "plan_id": "api-connect-kunde-and-sons-sleek-intelligent-granite-fish-product:1.0.0:default-plan",
  "plan_name": "default-plan",
  "plan_version": "1.0.0",
  "product_id": "8df85619-2a6f-472e-a094-7abe7b059e83",
  "product_name": "api-connect-kunde-and-sons-sleek-intelligent-granite-fish-product",
  "product_ref": "api-connect-kunde-and-sons-sleek-intelligent-granite-fish-product:1.0.0",
  "product_title": "API Connect Kunde and Sons - Sleek Intelligent Granite Fish Product",
  "product_version": "1.0.0",
  "query_string": "",
  "rate_limit": {
    "rate-limit": {
      "interval": 1,
      "count": 1621,
      "reject": "true",
      "unit": "hour",
      "period": 3600,
      "shared": "true",
      "limit": 100
    }
  },
  "request_body": "",
  "request_http_headers": [
    {
      "Accept": "application/json, text/plain, */*"
    },
    {
      "Accept-Encoding": "gzip, compress, deflate, br"
    },
    {
      "Host": "cdm0310-gw.server.dev.example.com"
    },
    {
      "User-Agent": "Mozilla/5.0 (Linux; Android 8.1.0; SAMSUNG SM-G610M) AppleWebKit/537.36 (KHTML, like Gecko) SamsungBrowser/23.0 Chrome/115.0.0.0 Mobile Safari/537.36"
    },
    {
      "Via": "1.1 BwAAAF4Hgnk-"
    },
    {
      "X-Client-IP": "9.46.111.156"
    },
    {
      "X-Forwarded-For": "106.27.171.34"
    },
    {
      "X-Global-Transaction-ID": "eba30d3065eef8d9000e5021"
    }
  ],
  "request_method": "GET",
  "request_protocol": "https",
  "resource_id": "p-2-p-bank-apis-api:1.0.0:get:/stores",
  "resource_path": "get",
  "response_body": "{ \"httpCode\":\"403\", \"httpMessage\":\"Forbidden\", \"moreInformation\":\"\" }",
  "response_http_headers": [
    {
      "Content-Type": "application/json"
    }
  ],
  "space_id": "d7442797-de03-4305-8f7e-6aa523589d1f",
  "space_name": "api-connect-space-2",
  "status_code": "403 Forbidden",
  "storage_max_queue": 7730941132,
  "storage_queue_size": 5162595,
  "tags": [
    "apicapievent",
    "_geoip_lookup_failure"
  ],
  "time_to_serve_request": "828",
  "transaction_id": "938017",
  "uri_path": "/boborg/api-connect-catalog-1/p-2-p-bank-apis-api/stores",
  "user_agent": {
    "device": "Samsung SM-G610M",
    "major": "23",
    "minor": "0",
    "name": "Samsung Internet",
    "os": "Android",
    "os_full": "Android 8.1.0",
    "os_major": "8",
    "os_minor": "1",
    "os_name": "Android",
    "os_patch": "0",
    "os_version": "8.1.0",
    "version": "23.0"
  },
  "gateway_geoip": {
    "ip": "9.79.12.126",
    "country_code2": "US",
    "country_code3": "USA",
    "country_name": "United States",
    "continent_code": "NA",
    "region_name": "NC",
    "city_name": "Durham",
    "postal_code": "27709",
    "latitude": 35.994,
    "longitude": -78.8986,
    "dma_code": 560,
    "area_code": 919,
    "timezone": "America/New_York",
    "real_region_name": "North Carolina",
    "location": [
      -78.8986,
      35.994
    ]
  }
}