Get our latest book on "Top 10 artificial intelligence myths."

Last updated

March 4, 2021

Table of contents

Reading data via Impira Read API

This guide will walk you through:

  • Reading your files or data via Impira Read API
  • Querying data via Impira Query Language (IQL) API
  • Polling for changes

See Impira Write API to learn how to upload files, write and update data, or delete files or data.

Reading files or data

To read data at a given path, you can use the GET verb. You do not need to specify a body for the request. However, you can specify a few optional query parameters:

  • fields is a comma separated list of fields. You can use this to select specific fields. By default, the read API returns all fields in a collection or dataset.
  • include_joins. By default, for performance reasons, the read API does not include joined fields. You can specify include_joins=true to include joined fields.
  • highest and lowest can be used to sort by a particular field. For example, highest=Price will sort records by the highest value of Price first.
  • offset and limit can help paginate long results. offset defines the starting point and limit constrains the total number of records returned. If you use offset and limit to paginate, you should specify a sort via highest or lowest otherwise you may duplicate or miss records.
  • Any other parameters are interpreted as filters. For example, if you have a field named Inspected, you can specify Inspected=true as a query parameter to only include records that have Inspected set to the value true.

Example requests

Return all records in the Applications collection.

curl -X GET "<YOUR_ORG_HERE>/api/v2/files" \
 --header "X-Access-Token: YOUR_TOKEN_HERE"

Return all records in the Applications collection.

``` language="js"
curl -X GET "<YOUR_ORG_HERE>/api/v2/collection/Applications" \
 --header "X-Access-Token: YOUR_TOKEN_HERE"

Return all records in the Applications collection with `Inspected=true`.

``` language="js"
curl -X GET "<YOUR_ORG_HERE>/api/v2/collection/Applications?Inspected=true" \
 --header "X-Access-Token: YOUR_TOKEN_HERE"

Return 10 records in the Applications collection.

``` language="js"
curl -X GET "<YOUR_ORG_HERE>/api/v2/collection/Applications?limit=10" \
 --header "X-Access-Token: YOUR_TOKEN_HERE"

Return 10 records in the Applications collection sorted by price.

``` language="js"
curl -X GET "<YOUR_ORG_HERE>/api/v2/collection/Applications?limit=10&lowest=Price" \
 --header "X-Access-Token: YOUR_TOKEN_HERE"

Querying data via Impira Query Language (IQL) API

You’ve extracted all the meaningful data from your documents and have it neatly organized in Impira. Now you’re ready to access your collection’s data via API. 

We’ll show you how to export your data in bulk, and how to use an IQL query to pinpoint specific data. 

API Access

Step 1: Create an API token

First, you’ll need to create an API token to authenticate your API requests. Impira’s use of token-authenticated API requests protects your data from unauthenticated access. We recommend using a unique token for each integration you set up so you can leave all your other integrations intact when removing any single token to block access in the future. 

To create a token:

  1. Go to the collection you want to work with.
  2. Click the gear icon in the top-right corner.
  3. Select API on the left.
  4. Click the + to the right of Token List

Give your token a name and you’ll be presented with a Token Value, which you can copy. Hold onto your Token Value for later. 

Step 2: Enter your Token Value

  1. Now, open your Terminal app and paste in:

curl -X GET "<YOUR_ORG_HERE>/api/v2/collection/Applications" \

  • Replace `<YOUR_ORG_HERE>` with your organization’s name (it’ll be in your browser’s URL bar, after `/o/`)
  • Replace `Applications` with your collection’s name (case-sensitive)

  1. Hit Enter.
  2. Paste in: 

--header "X-Access-Token: YOUR_TOKEN_HERE"

  • Replace `YOUR_TOKEN_HERE` with the Token Value you saved from Step 1. 

  1. Hit Enter twice.

Your Terminal will now display all the general data from your collection. If this is what you’re after, then you can go ahead and use this data as you see fit. But if you’d like to go further and hone in on specific data, move on to Step 3. 

Step 3: Using an IQL query

  1. Go back to your browser window and click the Experimental Features icon in the top-right corner and choose IQL Playground.

  1. Choose the collection you want to query (left sidebar) and select the Open in API to see the same data you pulled in Terminal in Step 2, but this time within a new browser tab. This is your collection’s general data.

Step 4: Getting specific with an IQL query

Now let’s get more specific with your data starting with just one row, then a field within that row.

  1. In the search bar, add a space after the code and enter `limit:1` This will give you one row to work with.
  2. Now, we’re going to isolate the File column data for this row. Enter a space after “limit:1” and enter `[File]`.

This is how specific and focused you can be by running a simple IQL query through the API. You can view this data in a new browser tab by clicking Open in API.

Step 5: Closing the loop

  1. Copy the URL from your API browser window. 
  2. Go to Terminal and enter:

curl -X GET ‘URL’

  • Replace `URL` with your copied URL from the API browser window. 

This will initially return with `“error": "no token provided.`, but this is expected. Now, let’s provide that token.

  1. Hit the up arrow, space, backslash (\), enter.
  2. Paste this into the next line:

--header "X-Access-Token: YOUR_TOKEN_HERE"

  • Replace `YOUR_TOKEN_HERE` with your Token Value from Step 1 and hit Enter.

You’ll now see the same data from Step 4 in your Terminal. 

Running large queries

If your query is long enough, the generated URL may exceed 2048 characters in length, making it impossible to submit a query through a `GET` request. To avoid hitting this limit, you can use a `POST` request instead to submit the query in the request body against the IQL API URL:


The body should be a JSON-encoded object with a `query` field containing the IQL query and an optional `defaultLimit` field with a limit on the number of results.

Example request

curl -X POST '<YOUR_ORG_HERE>/api/v2/iql' \
  --header 'X-Access-Token: YOUR_TOKEN_HERE'
  --data '{"query": "@files limit:1"}'

Polling for changes

The IQL API additionally supports polling for changes. This allows you to run a query and receive a cursor, which you can provide as a parameter the next time. The API won’t return any results until new events arrive after the cursor, and then return those new events.

Key concepts

The Impira runtime supports incremental execution over IQL queries (with some exceptions  noted below). This is the building block that makes Impira capable of incrementally retraining models, updating the UI in real-time, and providing Webhooks over your data. The poll API gives you access to this building block, so you can build powerful, real-time applications as well. Poll is an advanced feature, and in most cases, users can use the direct query API or webhooks.

Under the hood, Impira logs every change to data with an ordered cursor. These cursors are strings which can be compared lexicographically. The poll API allows you to specify a cursor alongside a query, and it’ll hold off on returning any results until the results of the query change, and then return a set of events with the changes and a new cursor.


The event format is very similar to the standard data format that the IQL and other APIs return. Each event includes three fields:

  • `data`: the full record corresponding to the event
  • `cursor`: the cursor at which the event occurred
  • `action`: delete or insert

The following example indicates that a record with uid “65d527f1d94521e5” should be inserted at cursor “0200000010862702816486”:

  "data": {
    "uid": "65d527f1d94521e5",
      "score": 0.5,
 "action": "insert",
 "cursor": "0200000010862702816486"

If you’re trying to maintain an up-to-date copy of the query (e.g., in a relational database that you’re syncing data into), you can, for most queries, use the `uid` as a primary key against which to upsert new records. If a new delete or insert record arrives, you can use the `uid` field to find the relevant row, and then delete or update it accordingly. Certain queries (e.g., those which do not project the uid or have a pivot operation) will have a different primary key. However, you can always compare the full row (directly or through a hash) as well.

Using the Poll API

To query the poll API, simply replace the `/iql` with `/poll`. If you don’t specify a cursor, then poll will automatically run against the latest cursor and provide you with a snapshot of insert events and a new cursor to subscribe to. You can use the cursor value it returns in the next query to block on changes by simply providing a `cursor=<cursor value>` parameter to the GET request.

More advanced IQL queries

Impira also supports much more advanced, SQL-like queries over your data. Explore advanced IQL queries here.

Stay in the loop

Get our Release Notes hot off the press, straight into your inbox.

Need more help?

Talk to someone