Query data via Axiom API

Learn how to use the Axiom API to query data.

This page explains how to query data via the Axiom API using the following:

• cURL
• Axiom Node.js library

For an introduction to the basics of the Axiom API and to the authentication options, see Introduction to Axiom API.

The API requests on this page use the query data endpoint. For more information, see the API reference.

Prerequisites

• Create an Axiom account.
• Create a dataset in Axiom where you send your data.
• Create an API token in Axiom with permissions to update the dataset you have created.

Query data with cURL

To query data with cURL:

1. Build the APL query. For more information, see Introduction to APL.
2. Encode the APL query as a JSON object and enter it into the body of the API request.
3. Optional: In the body of the request, set optional parameters such as startTime and endTime. For more information, see the query data API reference.
4. Set the Content-Type header to application/json.
5. Set the Authorization header to Bearer API_TOKEN.
6. Send the POST request to one of the following:
   • For tabular output, use https://AXIOM_DOMAIN/v1/datasets/_apl?format=tabular.
   • For legacy output, use https://AXIOM_DOMAIN/v1/datasets/_apl?format=legacy.

Example

curl --request POST \
  --url 'https://AXIOM_DOMAIN/v1/datasets/_apl?format=tabular' \
  --header 'Authorization: Bearer API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "apl": "DATASET_NAME | limit 10",
  "startTime": "string",
  "endTime": "string"
}'

Replace AXIOM_DOMAIN with api.axiom.co if your organization uses the US region, and with api.eu.axiom.co if your organization uses the EU region. For more information, see Regions.

Replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Replace DATASET_NAME with the name of the Axiom dataset where you want to send data.

Example response

{
  "format": "tabular",
  "status": {
    "elapsedTime": 260650,
    "minCursor": "0d8q6stroluyo-07c3957e7400015c-0000c875",
    "maxCursor": "0d8q6stroluyo-07c3957e7400015c-0000c877",
    "blocksExamined": 4,
    "blocksCached": 0,
    "blocksMatched": 0,
    "rowsExamined": 197604,
    "rowsMatched": 197604,
    "numGroups": 0,
    "isPartial": false,
    "cacheStatus": 1,
    "minBlockTime": "2025-03-26T12:03:14Z",
    "maxBlockTime": "2025-03-26T12:12:42Z"
  },
  "tables": [
    {
      "name": "0",
      "sources": [
        {
          "name": "DATASET_NAME"
        }
      ],
      "fields": [
        {
          "name": "_sysTime",
          "type": "datetime"
        },
        {
          "name": "_time",
          "type": "datetime"
        },
        {
          "name": "content_type",
          "type": "string"
        },
        {
          "name": "geo.city",
          "type": "string"
        },
        {
          "name": "geo.country",
          "type": "string"
        },
        {
          "name": "id",
          "type": "string"
        },
        {
          "name": "is_tls",
          "type": "boolean"
        },
        {
          "name": "message",
          "type": "string"
        },
        {
          "name": "method",
          "type": "string"
        },
        {
          "name": "req_duration_ms",
          "type": "float"
        },
        {
          "name": "resp_body_size_bytes",
          "type": "integer"
        },
        {
          "name": "resp_header_size_bytes",
          "type": "integer"
        },
        {
          "name": "server_datacenter",
          "type": "string"
        },
        {
          "name": "status",
          "type": "string"
        },
        {
          "name": "uri",
          "type": "string"
        },
        {
          "name": "user_agent",
          "type": "string"
        },
        {
          "name": "is_ok_2    ",
          "type": "boolean"
        },
        {
          "name": "city_str_len",
          "type": "integer"
        }
      ],
      "order": [
        {
          "field": "_time",
          "desc": true
        }
      ],
      "groups": [],
      "range": {
        "field": "_time",
        "start": "1970-01-01T00:00:00Z",
        "end": "2025-03-26T12:12:43Z"
      },
      "columns": [
        [
          "2025-03-26T12:12:42.68112905Z",
          "2025-03-26T12:12:42.68112905Z",
          "2025-03-26T12:12:42.68112905Z"
        ],
        [
          "2025-03-26T12:12:42Z",
          "2025-03-26T12:12:42Z",
          "2025-03-26T12:12:42Z"
        ],
        [
          "text/html",
          "text/plain-charset=utf-8",
          "image/jpeg"
        ],
        [
          "Ojinaga",
          "Humboldt",
          "Nevers"
        ],
        [
          "Mexico",
          "United States",
          "France"
        ],
        [
          "8af366cf-6f25-42e6-bbb4-d860ab535a60",
          "032e7f68-b0ab-47c0-a24a-35af566359e5",
          "4d2c7baa-ff28-4b1f-9db9-8e6c0ed5a9c9"
        ],
        [
          false,
          false,
          true
        ],
        [
          "QCD permutations were not solvable in linear time, expected compressed time",
          "QCD permutations were not solvable in linear time, expected compressed time",
          "Expected a new layer of particle physics but got a Higgs Boson"
        ],
        [
          "GET",
          "GET",
          "GET"
        ],
        [
          1.396373193863436,
          0.16252390534308514,
          0.4093416175186162
        ],
        [
          3448,
          2533,
          1906
        ],
        [
          84,
          31,
          29
        ],
        [
          "DCA",
          "GRU",
          "FRA"
        ],
        [
          "201",
          "200",
          "200"
        ],
        [
          "/api/v1/buy/commit/id/go",
          "/api/v1/textdata/cnfigs",
          "/api/v1/bank/warn"
        ],
        [
          "Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko",
          "Mozilla/5.0 (Windows NT 6.2; WOW64) AppleWebKit/535.24 (KHTML, like Gecko) Chrome/19.0.1055.1 Safari/535.24",
          "Mozilla/5.0 (Windows; U; MSIE 9.0; WIndows NT 9.0; en-US))"
        ],
        [
          true,
          true,
          true
        ],
        [
          7,
          8,
          6
        ]
      ]
    }
  ],
  "datasetNames": [
    "DATASET_NAME"
  ],
  "fieldsMetaMap": {
    "DATASET_NAME": [
      {
        "name": "status",
        "type": "",
        "unit": "",
        "hidden": false,
        "description": "HTTP status code"
      },
      {
        "name": "resp_header_size_bytes",
        "type": "integer",
        "unit": "none",
        "hidden": false,
        "description": ""
      },
      {
        "name": "geo.city",
        "type": "string",
        "unit": "",
        "hidden": false,
        "description": "the city"
      },
      {
        "name": "resp_body_size_bytes",
        "type": "integer",
        "unit": "decbytes",
        "hidden": false,
        "description": ""
      },
      {
        "name": "content_type",
        "type": "string",
        "unit": "",
        "hidden": false,
        "description": ""
      },
      {
        "name": "geo.country",
        "type": "string",
        "unit": "",
        "hidden": false,
        "description": ""
      },
      {
        "name": "req_duration_ms",
        "type": "float",
        "unit": "ms",
        "hidden": false,
        "description": "Request duration"
      }
    ]
  }
}

Query data with Axiom Node.js

1. Install and configure the Axiom Node.js library.

2. Build the APL query. For more information, see Introduction to APL.

3. Pass the APL query as a string to the axiom.query function.

   const res = await axiom.query(`['DATASET_NAME'] | where foo == 'bar' | limit 100`);
   console.log(res);
   

   Replace DATASET_NAME with the name of the Axiom dataset where you want to send data.

For more examples, see the examples in GitHub.

For more information on other libraries you can use to query data, see Send data.