API Technical Reference

This document lists all of the technical resources available on Keen API. This API is part of a developer preview and may change without notice!

Resource Inventory:

Versions Resource

URL https://api.keen.io/
Description Returns the available API versions. Please only use API version 3.0. Versions 1.0 and 2.0 will work but will be deprecated shortly.
Supported Methods
GET - Master Key
HEAD - Master Key

Example Response

[
  {
    "is_public": false,
    "url": "/1.0",
    "version": "1.0"
  },
  {
    "is_public": false,
    "url": "/2.0",
    "version": "2.0"
  },
  {
    "is_public": true,
    "url": "/3.0",
    "version": "3.0"
  }
]

Discovery Resource

URL https://api.keen.io/<version>
Description Returns the available child resources. Currently, the only child resource is the Projects Resource.
Supported Methods
GET - Master Key
HEAD - Master Key

Example Response

{
  "projects_resource_url": "/3.0/projects"
}

Projects Resource

URL https://api.keen.io/<version>/projects
Description Returns the projects accessible to the API user, as well as links to project sub-resources for discovery.
Supported Methods
GET - Master Key
HEAD - Master Key

Example Response

[
  {
    "api_key": "a62538e817dd49fc9101fd0c1fa3c892",
    "events": [
      {
        "name": "purchases",
        "url": "/3.0/projects/4fea721933da5b4e8e000002/purchases"
      },
      {
        "name": "level_up",
        "url": "/3.0/projects/4fea721933da5b4e8e000002/level_up"
      },
      {
        "name": "inventory_changes",
        "url": "/3.0/projects/4fea721933da5b4e8e000002/inventory_changes"
      },
      {
        "name": "login",
        "url": "/3.0/projects/4fea721933da5b4e8e000002/login"
      }
    ],
    "events_url": "/3.0/projects/4fea721933da5b4e8e000002/events",
    "id": "4fea721933da5b4e8e000002",
    "saved_queries": [],
    "name": "Click to Buy (iOS)",
    "queries_url": "/3.0/projects/4fea721933da5b4e8e000002/queries",
    "url": "/3.0/projects/4fea721933da5b4e8e000002"
  }
]

Project Row Resource

URL https://api.keen.io/<version>/projects/<project_id>
Description GET returns detailed information about the specific project, as well as links to related resources.
Supported Methods
GET - Master Key
HEAD - Master Key

Example Response

{
  "api_key": "a62538e817dd49fc9101fd0c1fa3c892",
  "events": [
    {
      "name": "purchases",
      "url": "/3.0/projects/4fea721933da5b4e8e000002/purchases"
    },
    {
      "name": "level_up",
      "url": "/3.0/projects/4fea721933da5b4e8e000002/level_up"
    },
    {
      "name": "inventory_changes",
      "url": "/3.0/projects/4fea721933da5b4e8e000002/inventory_changes"
    },
    {
      "name": "login",
      "url": "/3.0/projects/4fea721933da5b4e8e000002/login"
    }
  ],
  "events_url": "/3.0/projects/4fea721933da5b4e8e000002/events",
  "id": "4fea721933da5b4e8e000002",
  "saved_queries": [],
  "name": "Click to Buy (iOS)",
  "queries_url": "/3.0/projects/4fea721933da5b4e8e000002/queries",
  "url": "/3.0/projects/4fea721933da5b4e8e000002"
}

Event Resource

URL https://api.keen.io/<version>/projects/<project_id>/events
Description
GET returns schema information for all the event collections in this project, including properties and their type. It also returns links to sub-resources.
POST is for inserting multiple events in one or more collections, in a single request. See below for examples.
Supported Methods
GET - Master Key
HEAD - Master Key
POST - Write Key
POST Request Body JSON arrays of events. See example below

Note

Make sure to set the request header “Content-Type” to “application/json” for POSTs.

Query String Parameters

  • api_key - The Write/Read Key or API Key for the project containing the data you are analyzing. As an alternative to including api_key as a query string parameter, you can include it in the header. See Authentication for more information.

Example GET Response

[
  {
    "name": "purchases",
    "properties": {
      "item.id": "num",
      "item.on_sale": "bool",
      "item.price": "num",
      "quantity": "num",
      "screen.category": "string",
      "screen.name": "string",
      "user.has_paid": "bool",
      "user.id": "num",
      "user.level": "num",
      "user.prior_balance": "num",
      "user.referring_source": "string"
    },
    "url": "/3.0/projects/4fea721933da5b4e8e000002/events/purchases"
  },
  {
    "name": "level_up",
    "properties": {
      "from_level": "num",
      "level": "num",
      "screen.category": "string",
      "screen.name": "string",
      "to_level": "num",
      "user.has_paid": "bool",
      "user.id": "num",
      "user.level": "num",
      "user.prior_balance": "num",
      "user.referring_source": "string"
    },
    "url": "/3.0/projects/4fea721933da5b4e8e000002/events/level_up"
  },
  {
    "name": "inventory_changes",
    "properties": {
      "item.id": "num",
      "quantity": "num",
      "screen.category": "string",
      "screen.name": "string",
      "user.has_paid": "bool",
      "user.id": "num",
      "user.level": "num",
      "user.prior_balance": "num",
      "user.referring_source": "string"
    },
    "url": "/3.0/projects/4fea721933da5b4e8e000002/events/inventory_changes"
  },
  {
    "name": "login",
    "properties": {
      "user.email": "string",
      "user.id": "string",
      "user_agent.browser": "string",
      "user_agent.browser_version": "string",
      "user_agent.platform": "string"
    },
    "url": "/3.0/projects/4fea721933da5b4e8e000002/events/login"
  }
]

POST Request Body - Example of batch event posting

This example shows how multiple JSON events can be sent to Keen in a single POST. The API expects a JSON object whose keys are the names of each event collection you want to insert into. Each key should point to a list of events to insert for that event collection.

This example loads 3 events into the “purchases” event collection and 2 events into the “meme_generations” event collection.

When loading events in bulk, we recommend posts of 5,000 events or fewer. See Bulk Loading docs for more information.

Note

Make sure to set the request header “Content-Type” to “application/json” for POSTs.

{
  "purchases": [
    {
      "itemID": 22654,
      "price": 455.65,
      "color": "yellow",
      "size": "gigantic",
      "smell": "foul",
      "taste": "salty"
    },
    {
      "itemID": 22634,
      "price": 89.33,
      "color": "fuschia",
      "size": "medium",
      "smell": "suspicious",
      "taste": "milky"
     },
    {
      "itemID": 22632,
      "price": 3.51,
      "color": "mauve",
      "size": "medium",
      "smell": "oregano",
      "taste": "pepperoni"
    }
  ],
  "meme_generations": [
    {
      "memeID": 226342,
      "character": "Futurama Fry",
      "text": "Not sure if example is useful ... or just confusing"
    },
    {
      "memeID": 22632,
      "character": "Good Guy Greg",
      "text": "Finds error in Keen docs ... lets team@keen.io know about it"
     }
  ]
}

POST Request Body - Example with custom timestamps

This example shows how you can overwrite Keen’s timestamp by sending a keen.timestamp property value. By default, Keen clients will automatically set this time at the time your event is recorded.

If you are not using one of our client libraries and you don’t include this timestamp, Keen will automatically populate it at the time your event is received.

See Timestamp Data Type for more information about timestamps.

{
  "purchases": [
    {
      "keen": {
              "timestamp": "2012-06-06T19:10:39.205000Z"
      },
      "quantity": 5
    },
    {
      "keen": {
              "timestamp": "2012-06-06T20:10:39.205000Z"
      },
      "quantity": 25
    }
  ],
  "inventory_changes": [
    {
      "keen": {
        "timestamp": "2012-06-06T19:10:39.205000Z"
      },
      "quantity": 32
    },
    {
      "keen": {
        "timestamp": "2012-06-06T19:10:39.205000Z"
      },
      "quantity": 5
    }
  ]
}

Example POST Response

{
  "purchases": [
    {
      "success": true
    },
    {
      "success": true
    }
  ],
  "inventory_changes": [
    {
      "success": true
    },
    {
      "success": true
    }
  ]
}

Property Resource

URL https://api.keen.io/<version>/projects/<project_id>/events/<event_collection>/properties/<property_name>
Description
GET returns the property name, type, and a link to sub-resources.
DELETE is for removing a property and deleting all values stored with that property name.
Supported Methods
GET - Master Key
DELETE - Master Key
POST Request Body JSON arrays of events. See example below

Query String Parameters

  • api_key - The Write/Read Key or API Key for the project containing the data you are analyzing. As an alternative to including the api_key as a query string parameter, you may include it in the header. See Authentication for more information.

Example GET Response

{
    "property_name": "user.id",
    "url": "/3.0/projects/<project_id>/events/login/properties/user.id",
    "type": "string"
}

Event Collection Resource

URL https://api.keen.io/<version>/projects/<project_id>/events/<event_collection>
Description
GET returns available schema information for this event collection, including properties and their type. It also returns links to sub-resources.
GET is also available for inserting events through an Image Beacon or Redirect.
POST is for inserting one event at a time in a single request. Examples below.
DELETE is for deleting the entire event collection. This is irreversible and will only work for collections under 10k events.
Supported Methods
GET - Master Key for Schema, Write Key for inserting events
HEAD - Master Key
POST - Write Key
DELETE - Master Key
POST Request Body Single JSON event. See example below

Query String Parameters

  • api_key - The Write/Read Key or API Key for the project containing the data you are analyzing. As an alternative to including the api_key as a query string parameter, you may include it in the header. See Authentication for more information.
  • filters - The filters to use when deleting events. See Filters for more information.
  • timeframe - The timeframe to use when deleting events. See Timeframe for more information.
  • timezone - The timezone to use when specifying a timeframe (while deleting events). See Timezone for more infomration.
  • data - The event body you want to save to Keen IO, URL-encoded AND base-64 encoded.
  • redirect - The URL you want to redirect the user to after the event is saved. If you don’t include a protocol (http:// or https://), we’ll automatically add that for you.

Example GET Response

{
  "properties": {
    "item.id": "num",
    "item.on_sale": "bool",
    "item.price": "num",
    "quantity": "num",
    "screen.category": "string",
    "screen.name": "string",
    "user.has_paid": "bool",
    "user.id": "num",
    "user.level": "num",
    "user.prior_balance": "num",
    "user.referring_source": "string"
  }
}

POST Request Body

See Events & Event Data for more information about the shape of event data in Keen.

{
        "keen": {
                "timestamp": "2012-06-06T19:10:39.205000Z"
        },
        "type": "mouse_click",
        "x_coord": 720,
        "y_coord": 640
}

Example POST Response

{
        "created": true
}

Queries Resource

URL https://api.keen.io/<version>/projects/<project_id>/queries
Description GET returns the list of available queries and links to them. See Data Analysis APIs for more information on query types.
Supported Methods
GET - Master Key
HEAD - Master Key

Query String Parameters

  • api_key - The Write/Read Key or API Key for the project containing the data you are analyzing. As an alternative to including the api_key as a query string parameter, you may include it in the header. See Authentication for more information.

Example Response

{
  "count_unique_url": "/3.0/projects/4fea721933da5b4e8e000002/queries/count_unique",
  "count_url": "/3.0/projects/4fea721933da5b4e8e000002/queries/count",
  "extraction_url": "/3.0/projects/4fea721933da5b4e8e000002/queries/extraction",
  "funnel_url": "/3.0/projects/4fea721933da5b4e8e000002/queries/funnel",
  "select_unique_url": "/3.0/projects/4fea721933da5b4e8e000002/queries/select_unique"
}

Count Resource

URL https://api.keen.io/<version>/projects/<project_id>/queries/count
Description GET returns the number of resources in the event collection matching the given criteria. The response will be a simple JSON object with one key: a numeric result.
Supported Methods
GET - Read Key
HEAD - Read Key

Query String Parameters

  • api_key - The Write/Read Key or API Key for the project containing the data you are analyzing. As an alternative to including the api_key as a query string parameter, you may include it in the header. See Authentication for more information.
  • event_collection (required) - The name of the event collection you are analyzing.
  • filters (optional) - Filters are used to narrow down the events used in an analysis request based on event property values.
  • timeframe (optional) - A Timeframe specifies the events to use for analysis based on a window of time. If no timeframe is specified, all events will be counted.

Note

Adding Timeframe and Interval query string parameters will turn the Count request into a Series. See the documentation on Series for more information.

Example Response

{
    "result": 10
}

Count Unique Resource

URL https://api.keen.io/<version>/projects/<project_id>/queries/count_unique
Description GET returns the number of UNIQUE resources in the event collection matching the given criteria. The response will be a simple JSON object with one key: result, which maps to the numeric result described previously.
Supported Methods
GET - Read Key
HEAD - Read Key

Query String Parameters

  • api_key (optional) - Read Key for the project containing the data you are analyzing. If you don’t include it as a query string parameter you must include it in the header. See Authentication for more information.
  • event_collection (required) - The name of the event collection you are analyzing.
  • target_property (required) - The name of the property you are analyzing.
  • filters (optional) - Filters are used to narrow down the events used in an analysis request based on event property values.
  • timeframe (optional) - Similar to filters, a Timeframe is used to narrow down the events used in an analysis request based on the time that the event occurred.
  • timezone (optional) - Modifies the timeframe filters for Relative Timeframes to match a specific timezone.
  • group_by (optional) - The group_by parameter specifies the name of a property by which you would like to group the results. Using this parameter changes the response format. Read more about Group By to learn more.

Note

Adding group_by on a numeric metric will filter out non-numeric values automatically. See Numeric Aggregations on Non-Numbers for more information.

Note

Adding timeframe and interval query string parameters will turn the request into a Series. See the documentation on Series for more information.

Example Response

{
  "result": 7
}

Minimum Resource

URL https://api.keen.io/<version>/projects/<project_id>/queries/minimum
Description GET returns the minimum numeric value for the target property in the event collection matching the given criteria. Non-numeric values are ignored. The response will be a simple JSON object with one key: result, which maps to the numeric result described previously. The response will be a simple JSON object with one key: result, which maps to the numeric result described previously.
Supported Methods
GET - Read Key
HEAD - Read Key

Query String Parameters

  • api_key (optional) - Read Key for the project containing the data you are analyzing. If you don’t include it as a query string parameter you must include it in the header. See Authentication for more information.
  • event_collection (required) - The name of the event collection you are analyzing.
  • target_property (required) - The name of the property you are analyzing.
  • filters (optional) - Filters are used to narrow down the events used in an analysis request based on event property values.
  • timeframe (optional) - Similar to filters, a Timeframe is used to narrow down the events used in an analysis request based on the time that the event occurred.
  • timezone (optional) - Modifies the timeframe filters for Relative Timeframes to match a specific timezone.
  • group_by (optional) - The group_by parameter specifies the name of a property by which you would like to group the results. Using this parameter changes the response format. Read more about Group By to learn more.

Note

Adding group_by on a numeric metric will filter out non-numeric values automatically. See Numeric Aggregations on Non-Numbers for more information.

Note

Adding timeframe and interval query string parameters will turn the request into a Series. See the documentation on Series for more information.

Example Response

{
  "result": 7
}

Maximum Resource

URL https://api.keen.io/<version>/projects/<project_id>/queries/maximum
Description GET returns the maximum numeric value for the target property in the event collection matching the given criteria. Non-numeric values are ignored. The response will be a simple JSON object with one key: result, which maps to the numeric result described previously. The response will be a simple JSON object with one key: result, which maps to the numeric result described previously.
Supported Methods
GET - Read Key
HEAD - Read Key

Query String Parameters

  • api_key (optional) - Read Key for the project containing the data you are analyzing. If you don’t include it as a query string parameter you must include it in the header. See Authentication for more information.
  • event_collection (required) - The name of the event collection you are analyzing.
  • target_property (required) - The name of the property you are analyzing.
  • filters (optional) - Filters are used to narrow down the events used in an analysis request based on event property values.
  • timeframe (optional) - Similar to filters, a Timeframe is used to narrow down the events used in an analysis request based on the time that the event occurred.
  • timezone (optional) - Modifies the timeframe filters for Relative Timeframes to match a specific timezone.
  • group_by (optional) - The group_by parameter specifies the name of a property by which you would like to group the results. Using this parameter changes the response format. Read more about Group By to learn more.

Note

Adding group_by on a numeric metric will filter out non-numeric values automatically. See Numeric Aggregations on Non-Numbers for more information.

Note

Adding timeframe and interval query string parameters will turn the request into a Series. See the documentation on Series for more information.

Example Response

{
  "result": 7
}

Average Resource

URL https://api.keen.io/<version>/projects/<project_id>/queries/average
Description GET returns the average across all numeric values for the target property in the event collection matching the given criteria. Non-numeric values are ignored. The response will be a simple JSON object with one key: result, which maps to the numeric result described previously. The response will be a simple JSON object with one key: result, which maps to the numeric result described previously.
Supported Methods
GET - Read Key
HEAD - Read Key

Query String Parameters

  • api_key (optional) - Read Key for the project containing the data you are analyzing. If you don’t include it as a query string parameter you must include it in the header. See Authentication for more information.
  • event_collection (required) - The name of the event collection you are analyzing.
  • target_property (required) - The name of the property you are analyzing.
  • filters (optional) - Filters are used to narrow down the events used in an analysis request based on event property values.
  • timeframe (optional) - Similar to filters, a Timeframe is used to narrow down the events used in an analysis request based on the time that the event occurred.
  • timezone (optional) - Modifies the timeframe filters for Relative Timeframes to match a specific timezone.
  • group_by (optional) - The group_by parameter specifies the name of a property by which you would like to group the results. Using this parameter changes the response format. Read more about Group By to learn more.

Note

Adding group_by on a numeric metric will filter out non-numeric values automatically. See Numeric Aggregations on Non-Numbers for more information.

Note

Adding timeframe and interval query string parameters will turn the request into a Series. See the documentation on Series for more information.

Example Response

{
  "result": 7
}

Sum Resource

URL https://api.keen.io/<version>/projects/<project_id>/queries/sum
Description GET returns the sum of all numeric values for the target property in the event collection matching the given criteria. Non-numeric values are ignored. The response will be a simple JSON object with one key: result, which maps to the numeric result described previously. The response will be a simple JSON object with one key: result, which maps to the numeric result described previously.
Supported Methods
GET - Read Key
HEAD - Read Key

Query String Parameters

  • api_key (optional) - Read Key for the project containing the data you are analyzing. If you don’t include it as a query string parameter you must include it in the header. See Authentication for more information.
  • event_collection (required) - The name of the event collection you are analyzing.
  • target_property (required) - The name of the property you are analyzing.
  • filters (optional) - Filters are used to narrow down the events used in an analysis request based on event property values.
  • timeframe (optional) - Similar to filters, a Timeframe is used to narrow down the events used in an analysis request based on the time that the event occurred.
  • timezone (optional) - Modifies the timeframe filters for Relative Timeframes to match a specific timezone.
  • group_by (optional) - The group_by parameter specifies the name of a property by which you would like to group the results. Using this parameter changes the response format. Read more about Group By to learn more.

Note

Adding group_by on a numeric metric will filter out non-numeric values automatically. See Numeric Aggregations on Non-Numbers for more information.

Note

Adding timeframe and interval query string parameters will turn the request into a Series. See the documentation on Series for more information.

Example Response

{
  "result": 7
}

Select Unique Resource

URL https://api.keen.io/<version>/projects/<project_id>/queries/select_unique
Description GET returns a list of UNIQUE resources in the event collection matching the given criteria. The response will be a simple JSON object with one key: result, which maps to an array of unique property values.
Supported Methods
GET - Read Key
HEAD - Read Key

Query String Parameters

  • api_key - The Write/Read Key or API Key for the project containing the data you are analyzing. As an alternative to including the api_key as a query string parameter, you may include it in the header. See Authentication for more information.
  • event_collection (required) - The name of the event collection you are analyzing.
  • target_property (required) - The property of which you want to count the unique values.
  • filters (optional) - Filters are used to narrow down the events used in an analysis request based on event property values.
  • timeframe (optional) - Similar to filters, a Timeframe is used to narrow down the events used in an analysis request based on the time that the event occurred.

Note

Adding timeframe and interval query string parameters will turn the Select Unique request into a Series. See the documentation on Series for more information.

Example Response

{
    "result": ["hello", "goodbye", "welcome"]
}

Extraction Resource

URL https://api.keen.io/<version>/projects/<project_id>/queries/extraction
Description GET creates an extraction request for full-form event data with all property values. See Data Extractions for more details. If the query string parameter email is specified, then the extraction will be processed asynchronously and an e-mail will be sent to the specified address when it completes. The email will include a link to a downloadable CSV file. If email is omitted, then the extraction will be processed in-line and JSON results will be returned in the GET request.
Supported Methods
GET - Read Key
HEAD - Read Key

Query String Parameters

Extractions take the following parameters:

  • api_key (optional) - The API Key for the project containing the data you are analyzing. The API key can alternatively be provided in the request header. See Authentication for more information.
  • event_collection (required) - The name of the event collection you are analyzing.
  • filters (optional) - Filters are used to narrow down the events used in an analysis request based on event property values.
  • timeframe (optional) - A Timeframe specifies the events to use for analysis based on a window of time.
  • email (optional) - If an email address is specified, an email will be sent to it when your extraction is ready for download. If email is not specified, your extraction will be processed synchronously and your data will be returned as JSON.
  • latest (optional) - Use this parameter to specifically request the most recent events added to a given collection. Extract up to 100 of your most recent events.

Note

Series are not supported for the Extraction Resource. The interval query string parameter is not used here.

Example Response

GET (if email is specified)

{"result": "Processing. Check the specified email for the extraction results."}

GET (if email is not specified)

The result is an array of events like this:

{"result":[{
            "keen": {
                "created_at": "2012-07-30T21:21:46.566000+00:00",
                "timestamp": "2012-07-30T21:21:46.566000+00:00"
                    },
            "user": {
                "email": "dan@keen.io",
                "id": "4f4db6c7777d66ffff000000"
                    },
            "user_agent": {
                "browser": "chrome",
                "browser_version": "20.0.1132.57",
                "platform": "macos"
                          },
            },
            {
            "keen": {
                "created_at": "2012-07-30T21:40:05.386000+00:00",
                "timestamp": "2012-07-30T21:40:05.386000+00:00"
                    },
            "user": {
                "email": "michelle@keen.io",
                "id": "4fa2cccccf546ffff000006"
                    },
            "user_agent": {
                "browser": "chrome",
                "browser_version": "20.0.1132.57",
                "platform": "macos"
                          }
            }
        ]
}

Wardrobe Resource

URL https://api.keen.io/<version>/projects/523b527836bf5a3216000006/events/wardrobe
Description
Use this resource to request a garment of a given size to a given address. This is really just the Event Collect Resource, except you must use a specific project ID, write key, and collection name. See below.
POST is for inserting one event at a time in a single request, for a single person. Examples below.
Note: Wardrobe resource has questionable availability and response time depending on inventory, expense to ship to your country, trolls, team temperament, and our willingness to visit the post office in a given week.
Supported Methods POST - Write Key
POST Request Body Single JSON event. See example below

Query String Parameters

See our Getting Started Guide for an example of sending an event.

POST Request Body

{
        "name": "Lara Croft",
        "email": "lara@lcroft.com",
        "address_line_1": "2624 15th Ave",
        "address_line_2": "Apt 1",
        "city": "San Francisco",
        "state": "CA",
        "zip": 94127,
        "country": "USA",
        "garment_gender": "Women's",
        "size": "L"
}

Example POST Response

{
        "created": true
}

Funnel Resource

URL https://api.keen.io/<version>/projects/<project_id>/queries/funnel
Description Funnels count relevant events in succession. See Funnels for more details!
Supported Methods
GET - Read Key
HEAD - Read Key

Query String Parameters

  • api_key - The Write/Read Key or API Key for the project containing the data you are analyzing. As an alternative to including the api_key as a query string parameter, you may include it in the header. See Authentication for more information.
  • steps (required) - A URL encoded JSON Array defining the Steps in the Funnel.

Note

Series are not supported for the Funnel Resource. The interval query string parameter is not used here.

Example Response

{
  "result": [
    2,
    1
  ],
  "steps": [
    {
      "actor_property": [
        "username"
      ],
      "event_collection": "landed",
      "filters": [
        {
          "operator": "eq",
          "property_name": "device",
          "property_value": "Android"
        }
      ]
    },
    {
      "actor_property": [
        "username"
      ],
      "event_collection": "signed_up",
      "filters": [
        {
          "operator": "eq",
          "property_name": "device",
          "property_value": "Android"
        }
      ]
    }
  ]
}

Saved Queries List Resource

URL https://api.keen.io/<version>/projects/<project_id>/saved_queries
Description GET returns all the available Saved Queries for the specified project as well as links to child-resources.
Supported Methods
GET - Master Key
HEAD - Master Key

Query String Parameters

  • api_key - The Write/Read Key or API Key for the project containing the data you are analyzing. If you don’t include it as a query string parameter you must include it in the header. See Authentication for more information.

Example Response

[
  {
    "analysis_type": "count",
    "created_date": "2012-09-14T22:23:50.259000",
    "event_collection": "foo",
    "filters": [],
    "query_name": "query_one",
    "query_type": "metric",
    "interval": null,
    "last_modified_date": "2012-09-14T22:23:50.259000",
    "timeframe": null,
    "urls": {
      "saved_query_results_url": "/3.0/projects/abc/saved_queries/query_one/result",
      "saved_query_url": "/3.0/projects/abc/saved_queries/query_one"
    }
  },
  {
    "analysis_type": "count",
    "created_date": "2012-09-14T22:23:50.288000",
    "event_collection": "bar",
    "filters": [],
    "query_name": "query_two",
    "query_type": "metric",
    "interval": null,
    "last_modified_date": "2012-09-14T22:23:50.288000",
    "timeframe": null,
    "urls": {
      "saved_query_results_url": "/3.0/projects/abc/saved_queries/query_two/result",
      "saved_query_url": "/3.0/projects/abc/saved_queries/query_two"
    }
  }
]

Saved Query Row Resource

URL https://api.keen.io/<version>/projects/<project_id>/saved_queries/<saved_query_name>
Description
GET returns information about the specified Saved Query and includes links to child-resources.
PUT either inserts a new Saved Query if it doesn’t already exist, or updates an existing Saved Query if it does exist.
DELETE just plain old deletes the Saved Query.
Supported Methods
GET - Master Key
HEAD - Master Key
PUT - Master Key
DELETE - Master Key

Notes

When inserting a new Saved Query, the body of the PUT request should be a JSON object with all the required properties for that particular analysis type. The optional properties, are, well, optional.

When updating a Saved Query, the body of the PUT request only needs to include the properties you want to update. For example, if you have a Saved Query that does a Count and want to change its Filters, just include the filters property.

Note

If you update a Saved Query’s analysis_type and the NEW type doesn’t allow for some of the properties of the OLD type, Keen will delete the definition of those properties. For example, if you have a Saved Query that does a Count Unique and you change it to do a Count, we will delete the target_property property.

Note

Make sure to set the request header “Content-Type” to “application/json” for PUTs.

Query String Parameters

The two parameters required for every Saved Query are:

  • saved_query_name - The name of the Saved Query. This goes in the URL.
  • analysis_type - The type of analysis this Saved Query is doing. Valid values are “count”, “count_unique”, “select_unique”, “minimum”, “maximum”, “average”, “sum”, “extraction”, and “funnel”.

There are a number of read-only, Keen-specified properties available on a Saved Query once it’s been created. They are:

  • saved_query_type - Returns if the Saved Query is a “metric”, a “series”, an “extraction”, or a “funnel”.
  • created_date - When the Saved Query was created.
  • last_modified_date - When the Saved Query was last modified.

Then there are the properties for each specific analysis type. The table below describes all the properties that might appear in a Saved Query and which analysis types they’re applicable to. Please refer to the Data Analysis APIs documentation for full descriptions of what each of these do.

Property Name Count Count Unique, Select Unique, Minimum, Maximum, Average, Sum Extraction Funnel
saved_query_name Required Required Required Required
analysis_type Required Required Required Required
event_collection Required Required Required N/A
target_property N/A Required Required N/A
filters Optional Optional Optional Optional
timeframe Optional Optional Optional N/A
timezone Optional Optional Optional N/A
interval Optional Optional N/A N/A
email N/A N/A Optional N/A
steps N/A N/A N/A Optional
group_by Optional Optional N/A N/A

Example GET Response

{
  "analysis_type": "count",
  "created_date": "2012-09-14T22:23:50.259000",
  "event_collection": "foo",
  "filters": [],
  "query_name": "query_three",
  "query_type": "metric",
  "interval": null,
  "last_modified_date": "2012-09-14T22:23:50.259000",
  "timeframe": null,
  "urls": {
    "saved_query_results_url": "/3.0/projects/abc/saved_queries/query_three/result",
    "saved_query_url": "/3.0/projects/abc/saved_queries/query_three"
  }
}

PUT Request Body

{
  "analysis_type": "count",
  "event_collection": "foo"
}

Example POST Response

{
  "created": true,
  "saved_query": {
    "analysis_type": "count",
    "created_date": "2012-09-14T22:23:50.259178",
    "event_collection": "foo",
    "filters": [],
    "query_name": "query_four",
    "query_type": "metric",
    "interval": null,
    "last_modified_date": "2012-09-14T22:23:50.259178",
    "timeframe": null,
    "urls": {
      "saved_query_results_url": "/3.0/projects/abc/saved_queries/query_four/result",
      "saved_query_url": "/3.0/projects/abc/saved_queries/query_four"
    }
  },
  "updated": false
}

Saved Query Row Result Resource

URL https://api.keen.io/<version>/projects/<project_id>/saved_queries/<saved_query_name>/result
Description GET returns the results of the specified Saved Query.
Supported Methods
GET - Read Key
HEAD - Read Key

Example Response

{
  "result": 5
}

So, what are you waiting for? It only takes a few minutes and a few lines of code to start collecting the events that really matter to you.

Sign Up Free