Send data to Axiom via API

This page explains how to send to Axiom using the API.

The Axiom REST API accepts the following data formats:

• JSON
• NDJSON
• CSV

This page explains how to send data to Axiom via cURL commands in each of these formats, and how to send data with the Axiom Node.js library.

For more information on other ingest options, see Send data.

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 ingest 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.

Send data in JSON format

To send data to Axiom in JSON format:

1. Encode the events as JSON objects.
2. Enter the array of JSON objects into the body of the API request.
3. Optional: In the body of the request, set optional parameters such as timestamp-field and timestamp-format. For more information, see the ingest 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 https://AXIOM_DOMAIN/v1/datasets/DATASET_NAME/ingest.

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 with grouped events

The following example request contains grouped events. The structure of the JSON payload has the scheme of [ { "labels": { "key1": "value1", "key2": "value2" } }, ] where the array contains one or more JSON objects describing events.

Example request

curl -X 'POST' 'https://AXIOM_DOMAIN/v1/datasets/DATASET_NAME/ingest' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[
        {
          "time":"2025-01-12T00:00:00.000Z",
          "data":{"key1":"value1","key2":"value2"}
        },
        {
          "data":{"key3":"value3"},
          "labels":{"key4":"value4"}
        }
      ]'

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

{
    "ingested": 2,
    "failed": 0,
    "failures": [],
    "processedBytes": 219,
    "blocksCreated": 0,
    "walLength": 2
}

Example with nested arrays

Example request

curl -X 'POST' 'https://AXIOM_DOMAIN/v1/datasets/DATASET_NAME/ingest' \
    -H 'Authorization: Bearer API_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '[
            {
            "axiom": [{
                "logging":[{
                    "observability":[{
                        "location":[{
                            "credentials":[{
                                "datasets":[{
                                    "first_name":"axiom",
                                    "last_name":"logging",
                                    "location":"global"
                                }],
                                "work":[{
                                    "details":"https://app.axiom.co/",
                                    "tutorials":"https://www.axiom.co/blog",
                                    "changelog":"https://www.axiom.co/changelog",
                                    "documentation": "https://www.axiom.co/docs"
                                }]
                            }],
                            "social_media":[{
                                "details":[{
                                    "twitter":"https://twitter.com/AxiomFM",
                                    "linkedin":"https://linkedin.com/company/axiomhq",
                                    "github":"https://github.com/axiomhq"
                                }],
                                "features":[{
                                    "datasets":"view logs",
                                    "stream":"live_tail",
                                    "explorer":"queries"
                                }]
                            }]
                        }]
                    }],
                    "logs":[{
                        "apl": "functions"
                    }]
                }],
                "storage":[{}]
            }]}
        ]'

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

{
    "ingested":1,
    "failed":0,
    "failures":[],
    "processedBytes":1587,
    "blocksCreated":0,
    "walLength":3
}

Example with objects, strings, and arrays

Example request

curl -X 'POST' 'https://AXIOM_DOMAIN/v1/datasets/DATASET_NAME/ingest' \
    -H 'Authorization: Bearer API_TOKEN' \
    -H 'Content-Type: application/json' \
    -d '[{ "axiom": {
        "logging": {
            "observability": [
                { "apl": 23, "function": "tostring" },
                { "apl": 24, "operator": "summarize" }
            ],
            "axiom": [
                { "stream": "livetail", "datasets": [4, 0, 16], "logging": "observability", "metrics": 8, "dashboard": 10, "alerting": "kubernetes" }
            ]
        },
        "apl": {
            "reference":
                [[80, 12], [30, 40]]
        }
    }
    }]'

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

{
    "ingested":1,
    "failed":0,
    "failures":[],
    "processedBytes":432,
    "blocksCreated":0,
    "walLength":4
}

Send data in NDJSON format

To send data to Axiom in NDJSON format:

1. Encode the events as JSON objects.
2. Enter each JSON object in a separate line into the body of the API request.
3. Optional: In the body of the request, set optional parameters such as timestamp-field and timestamp-format. For more information, see the ingest data API reference.
4. Set the Content-Type header to either application/json or application/x-ndjson.
5. Set the Authorization header to Bearer API_TOKEN. Replace API_TOKEN with the Axiom API token you have generated.
6. Send the POST request to https://AXIOM_DOMAIN/v1/datasets/DATASET_NAME/ingest. Replace DATASET_NAME with the name of the Axiom dataset where you want to send data.

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 request

curl -X 'POST' 'https://AXIOM_DOMAIN/v1/datasets/DATASET_NAME/ingest' \
    -H 'Authorization: Bearer API_TOKEN' \
    -H 'Content-Type: application/x-ndjson' \
    -d '{"id":1,"name":"machala"}
        {"id":2,"name":"axiom"}
        {"id":3,"name":"apl"}
        {"index": {"_index": "products"}}
        {"timestamp": "2016-06-06T12:00:00+02:00", "attributes": {"key1": "value1","key2": "value2"}}
        {"queryString": "count()"}'

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

{
    "ingested": 6,
    "failed": 0,
    "failures": [],
    "processedBytes": 266,
    "blocksCreated": 0,
    "walLength": 6
}

Send data in CSV format

To send data to Axiom in JSON format:

1. Encode the events in CSV format. The first line specifies the field names separated by commas. Subsequent new lines specify the values separated by commas.
2. Enter the CSV representation in the body of the API request.
3. Optional: In the body of the request, set optional parameters such as timestamp-field and timestamp-format. For more information, see the ingest data API reference.
4. Set the Content-Type header to text/csv.
5. Set the Authorization header to Bearer API_TOKEN. Replace API_TOKEN with the Axiom API token you have generated.
6. Send the POST request to https://AXIOM_DOMAIN/v1/datasets/DATASET_NAME/ingest. Replace DATASET_NAME with the name of the Axiom dataset where you want to send data.

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.

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.

Example request

curl -X 'POST' 'https://AXIOM_DOMAIN/v1/datasets/DATASET_NAME/ingest' \
    -H 'Authorization: Bearer API_TOKEN' \
    -H 'Content-Type: text/csv' \
    -d 'user, name
        foo, bar'

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

{
    "ingested": 1,
    "failed": 0,
    "failures": [],
    "processedBytes": 28,
    "blocksCreated": 0,
    "walLength": 2
}

Send data with Axiom Node.js

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

2. Encode the events as JSON objects.

3. Pass the dataset name and the array of JSON objects to the axiom.ingest function.

   axiom.ingest('DATASET_NAME', [{ foo: 'bar' }]);
   await axiom.flush();
   

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.

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

What’s next

After ingesting data to Axiom, you can query it via API or the Axiom app UI.