---
title: "Query dataset"
method: POST
path: "/{dataset}/{version}"
tags: ["Data"]
---

# Query dataset

`POST /{dataset}/{version}`

Agnitio data queries are performed by assembling a JSON description of the query and POSTing it to the specific dataset you wish to query.
The query structure has two required fields: `metrics` and `constraints`.

The `metrics` field is an array of objects which describe which metrics you would like queried and returned.
These objects have a required `name` field which specifies which metric is desired. They also have an optional `as` field
which allows you to determine what the metric is called in the response.

The `constraints` field is an array of objects which describe how the dimensions of the dataset should be limited and aggregated.
The `map` field in the request constraints maps from the codes defined by the dimension's taxonomy to user defined values that will be returned in the response.

In addition to the `map` field, you can use a shorthand option as well known as `mapLevel` to roll out a given parent to all of its children as individual mappings at a specified level.

The API also supports operations like Location Quotient and Shift Share, as well as sorting, offsets, and limits for pagination.

## Path parameters

- `version` string, required

## Query parameters

- `dataset` 'global' | 'global_plus'

## Request body

- object
  - `metrics` object[], required — An array of objects which describe which metrics you would like queried and returned.
    - `name` string, required — Specifies which metric is desired.
    - `as` string — Allows you to determine what the metric is called in the response.
    - `operation` object — Optional operation to perform on the metric
      - `name` 'LocationQuotient' | 'ShiftShare' — Location Quotient: measure of geographical concentration applied to summable measures such as jobs or establishments. Can be calculated on datasets with an `Area` dimension. Shift Share: attempts to explain what factors cause a change in a measure over time. Use on datasets with an `Area` dimension and metrics with a time component:
      - `geoparent` string — The code of a parent value in the area dimension; use national or containing state, for example.
      - `along` string — The dimension to perform the comparison along. Usually `Industry` or `Occupation`.
      - `base` string — The start metric for the comparison. Used with ShiftShare
  - `constraints` object[], required — An array of objects which describe how the dimensions of the dataset should be limited and aggregated.
    - `dimensionName` string, required
    - `map` object — Maps from the codes defined by the dimension's taxonomy to user defined values that will be returned in the response.
    - `mapLevel` object — Shorthand for mapping all children at a specified level.
      - `level` integer
      - `predicate` integer[]
  - `sortBy` object[] — Return responses in a sorted order.
    - `name` string
    - `direction` 'ascending' | 'descending'
  - `offset` integer — Pagination offset
  - `limit` integer — Pagination limit

## Response `200`

OK

- object
  - `data` object[], required
    - `name` string
    - `type` string
    - `rows` union[]
      - union
        - string
        - number
  - `errors` unknown[], required
    - unknown
  - `timings` string[], required
  - `totalRows` integer, required

---

[API](https://skmtc.net/lightcast/apis/alumni-pathways-2-0.md) · [All operations](https://skmtc.net/lightcast/apis/alumni-pathways-2-0/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lightcast/alumni-pathways-2-0/revisions/fc66b9877391/schema)