# Grid API Columns

style

table td:first-child {
  white-space: nowrap;
}

Every time you request data from the Grid API, you must specify which columns to include in the results.

Each entity type has its own columns you can choose from. For convenience, many entities share
the same columns. For example, Cookies and Tags include columns about the configurations for the
audits that found the data and columns that describe the Pages where the Cookies and Tags were found.
Think of these columns as SQL `JOIN`s to the other entity types, so you don't have to perform a
join explicitly.

The Grid API is self documenting, meaning you can query the API to see the list of available columns for each entity.

To see the list of available columns for each entity do a `GET` request to the entity's **schema** endpoint.
For example, for the `pages` entity, you can do a `GET` request to `/v3/reports/grid/pages/schema`, which
will return a JSON description of each column:


```javascript Example GET to https://api.observepoint.com/v3/reports/grid/pages/schema
{
  "columns": [
    {
      "columnId": "PAGE_TITLE",
      "type": "string",
      ...
    },
    {
      "columnId": "FINAL_PAGE_URL",
      "type": "string",
      ...
    },
    ...
}
```

# Column Types

Every column has a "type" that tells you what kind of data to expect:

| Column Type | Description | Examples |
|  --- | --- | --- |
| `string` | Text | Audit names, URLs, tag vendor names |
| `number` | An integer or decimal number | `12345`, `12.345` |
| `timestamp` | A date and time as an [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html) string | `"2025-01-02T03:04:05.000+00:00"` |
| `boolean` | A yes/no value represented as a 1 or 0 | `1` or `0` |
| `entity_reference` | A value that refers to another object, usually consisting of multiple properties | An audit: `[1234, "My Audit Name"]`A tag: `["Google Analytics", 1234]`An array of cookie names: `["cookie1", "cookie2"]`A folder: `[1234, "My Folder Name"]`A web journey run status: `1` |
| `id` | A unique identifier for an entity | An audit ID, a tag ID, etc. |


# Units

You can assume certain units for certain kinds of `number` columns:

| Number Type | Unit | Notes |
|  --- | --- | --- |
| Durations | Milliseconds | All durations are returned in milliseconds |
| Sizes | Bytes | All sizes are returned in bytes |


# Entity References

Entity references are a special type of column whose format varies from column to column. The `schema` endpoint describes
what you can expect for `entity_reference` columns, with the following properties:

| Property | Description |
|  --- | --- |
| `referenceType` | For `entity_reference` columns that refer to other objects, this property contains a string that tells you what kind of object it is.Example values: `"audit"`, `"location"`, `"label"`, `"user"`, `"tag_vendor"`, `"country"`, and many others. |
| `isEnum` | `true` or `false`: Tells you whether the `entity_reference` is an enum.Enum values are numbers that represent a status or state numerically. |
| `isList` | When `true`, this means the column contains a **list** of other entity references. |
| `fields` | An array of objects that describe each element to expect in the entity reference data.Examples: |


Here are some common examples of entity references:

### Example: Folders

The `FOLDER` column is a reference to a folder. The `FOLDER` columns contains an array of values that tell you
know about the folder.

Example `FOLDER` value: `[1234, "My Folder Name"]`

The first value is the folder ID, and the second value is the folder name.

The `schema` endpoint describes the `FOLDER` column as follows:


```javascript Example FOLDER column schema
{
    "columnId": "FOLDER",
    "type": "entity_reference",
    ... // other properties omitted for brevity

    // The "referenceType" property tells you what kind of entity this is:
    "referenceType": "folder",

    // This entity_reference is not an enum or a list:
    "isEnum": false,
    "isList": false

    // The "fields" property describes each element to expect in the entity reference data,
    // which refer to other column IDs:
    "fields": [
        {
            "fieldName": "id",
            "columnId": "FOLDER_ID"
        },
        {
            "fieldName": "name",
            "columnId": "FOLDER_NAME"
        }
    ]
}
```

### Example: Labels

The `LABELS` column contains a list of label IDs.

Example `LABELS` value: `[1234, 5678]`

Each value is a label ID. You can use the `/v2/labels` API endpoint to map label IDs to label names.


```javascript Example LABELS column schema
{
    "columnId": "LABELS",
    "type": "entity_reference",
    ... // other properties omitted for brevity

    // Tells you that the IDs in this field refer to labels:
    "referenceType": "label",

    // This is not an enum value:
    "isEnum": false,

    // This field returns a list of values (rather than a single value) 
    "isList": true

    // This tells you that each element in the list consists of a label ID:
    "fields": [
        {
            "fieldName": "id"
        }
    ],
}
```