Ingesting data

This API allows you to send and load data into Axiom. You can use different methods to ingest logs depending on your requirements and log format.

Authorization and Headers

The only expected headers are the Authorization: Bearer, which is your API or Personal Token, and X-Axiom-Org-ID, which is your organization id. Learn more about API Token and Org ID.

Using Curl command to Ingest data

Individual events are ingested as an HTTP POST request.

POST api.axiom.co/v1

curl -X POST 'https://api.axiom.co/v1/ingest' \
  -H 'Authorization: Bearer $API_TOKEN' \
  -H 'Content-Type: application/x-ndjson' \
  -H 'X-Axiom-Org-ID: <$ORG_ID>' \
  -d '{  \"description\": \"string\",  \"name\": \"string\",  \"scopes\": [ \"string\" ]}'

Body Specification

The body of the POST should be a JSON encoded object containing key/value pairs. As an example, to report a GET request from the users, /download path with a duration of 231ms and a response size of 3012.

{ "path": "/download", "method": "GET", "duration_ms": 231, "res_size_bytes": 3012 }'

Axiom supports ingestion of different data formats:

  • application/json
  • application/x-ndjson
  • text/csv

Examples

These examples send an API event to Axiom. Before getting started with Axiom API, you need to create a Dataset and API Token.

Ingest Events using NDJSON

NDJSON consists of individual lines where each individual line is any valid JSON text and each line is delimited with a newline character. The NDJSON payload should have the scheme of {"id":1,"name":"Alice"} {"id":2,"name":"Bob"} {"id":3,"name":"Carol"}

Example Request using NDJSON

curl -X 'POST' 'https://api.axiom.co/v1/datasets/$DATASET_NAME/ingest' \
  -H 'Authorization: Bearer $API_TOKEN' \
  -H 'Content-Type: application/x-ndjson' \
  -d '{ "path": "/download", "method": "POST", "duration_ms": 231, "res_size_bytes": 3012, "endpoint":"/foo" }'

Response Example

A successful POST Request returns a 200 response code JSON with details:

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

More examples

curl -X 'POST' 'https://api.axiom.co/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()"}''

Example Response

A successful POST Request returns a 200 response code JSON with details:

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

Ingest Events using JSON

The following example request contains grouped events. The structure of the JSON payload should have the scheme of [ { "labels": { "key1": "value1", "key2": "value12" } }, ], in which the array comprises of one or more JSON objects describing Events.

Example Request using JSON

curl -X 'POST' 'https://api.axiom.co/v1/datasets/$DATASET_NAME/ingest' \
  -H 'Authorization: Bearer $API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '[
        {
          "time":"2021-23-04302:11:23.222Z",
          "data":{"key1":"value1","key2":"value2"}
        },
        {
          "data":{"key3":"value3"},
          "labels":{"key4":"value4"}
        }
      ]'

Example Response

A successful POST Request returns a 200 response code JSON with details:

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

Example Request using Nested Arrays

curl -X 'POST' 'https://api.axiom.co/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":[{}]
        }]}
      ]'

Example Response

A successful POST Request returns a 200 response code JSON with details:

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

Example Request using Objects, Strings, and Arrays

curl -X 'POST' 'https://api.axiom.co/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]]
    }
  }
}]'

Example Response

A successful POST Request returns a 200 response code JSON with details:

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

Ingest Events using CSV

The following example request contains events. The structure of the CSV payload uses a comma to separate values 'value1, value2, value3'.

Example Request using CSV

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

Example Response

A successful POST Request returns a 200 response code JSON with details:

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

Supported data types:

  • Strings
  • Numbers
  • Arrays of objects
  • Booleans
  • Objects

Datasets names are usually case sensitive, Dataset names must be between 1-128 characters, and may only contain ASCII alphanumeric characters and the '-' character.

Was this page helpful?