# Grid Reporting API

ObservePoint's Grid Reporting API gives developers access to all of ObservePoint's data about your websites.

# What is the Grid API?

The ObservePoint Grid API lets developers get all the data that powers [ObservePoint reports](https://help.observepoint.com/en/articles/11084158-reports-overview).
It's called the "Grid" API because it returns rows and columns.

The Grid API lets you filter, sort, group, and paginate the data you want.

It provides this data as a dense JSON array and lets you export the data as CSV, TSV, Excel, and Parquet.

# How do I use the Grid API?

### Authentication

The Grid API uses the same authentication as the rest of the ObservePoint API. For details, see [authentication](/#authentication).

### Getting Data

Make a `POST` request to the Grid API containing JSON that describes the data you want.

To build your request:

1. [Choose the entity type to query](/sections/grid-api-entities)
2. [Choose columns](/sections/grid-api-columns)
3. [Apply filters](/sections/grid-api-filters) (optional)
4. [Choose sort order](/sections/grid-api-sorting) (optional)
5. [Choose pagination](/sections/grid-api-pagination) (optional)
6. [Choose grouping](/sections/grid-api-grouping) (optional)


Once you've chosen the above, get the data by sending a `POST` request to the entity's endpoint.

Include these headers:

* `Authorization`: `api_key <your-api-key-goes-here>`
* `Content-Type`: `application/json`


Send the following JSON in the request body:

The JSON may seem big, but that's because it's expressive and powerful!


```javascript Example POST to https://api.observepoint.com/v3/reports/grid/<entity-type>
{ 
  // Specify the columns you want in this array:
  "columns": [
    { 
      "columnId": "EXAMPLE_COLUMN_ID"
    },
    {
      "columnId": "ANOTHER_EXAMPLE_COLUMN_ID"
    }
    // Add more column IDs here if you want
  ],
  "sortBy": [
    {
      "columnIndex": 0, // 0-based column index in the `columns` array above
      "sortDesc": false
    },
    // (optional) Sort by a 2nd column to break ties in the 1st sort column
    //{
    //  "columnIndex": 2,
    //  "sortDesc": true
    //}
  ],
  // Specify your filters here (optional):
  "filters": {
    "conditionsMatchMode": "all", // if you have more than 1 filter, specify "all" or "any"
    "conditions": [
      {
        "operator": "string_contains", // see the filters doc for supported operators
        "arg": "example string to filter by",
        "filteredColumn": {
          "columnId": "EXAMPLE_COLUMN_ID" // the column on which to apply the filter
        }
      }
    ]
  },
  // Pagination (optional):
  "page": 0,  // 0-based pagination
  "size": 10000 // number of rows to return, max 10,000
}
```

# Getting Results

The response is JSON that includes the rows that match your request.

To save space, the Grid API returns the data as a 2-dimensional array of arrays, where each array represents one row.


```javascript Sample results
{
  "metadata": {
    // For convenience, this is the list of columns you requested,
    // in the order you requested them
    "headers": [
      {"column": {"columnId": "EXAMPLE_COLUMN_ID"}},
      {"column": {"columnId": "ANOTHER_EXAMPLE_COLUMN_ID"}}
    ],
    // The pagination tells you if there are more rows to request
    "pagination": {
      "totalCount": 42000,
      "totalPageCount": 5,
      "pageSize": 10000,
      "currentPageSize": 10000,
      "currentPageNumber": 0
    },
  },
  // The actual data is encoded as a dense array to save space:
  "rows": [
    ["Example Value 1", "https://example.com/value1"],
    ["Example Value 2", "https://example.com/value2"]
    // 9,998 more rows here
  ]
}
```