Skip to content
Grid Reporting API/
/
Start a grid data export

Grid reports API by Observepoint

This section documents the API endpoints for using the ObservePoint Grid API, which provides access to ObservePoint data in row/column format.

Download OpenAPI description
GRID-API.openapi.json
GRID-API.openapi.yaml
Overview
URL
https://www.observepoint.com/contact-us
Languages
Servers
ObservePoint Production API
https://api.observepoint.com/

Get Grid Data

Request

POST /v3/reports/grid/{gridEntityType}

This is the main endpoint for the Grid API. It lets you request data in row/column format for the entities that ObservePoint has collected about your website

Security
API_Key
Path
gridEntityTypestringrequired

The grid entity type for which you want to query data

Enum"web-audit-runs""web-journey-runs""pages""cookies""tags""tag-variables""links""accessibility-issues""network-requests""browser-logs"
Bodyapplication/json
sizeinteger[ 10 .. 10000 ]

how many rows to include in the paginated response

pageinteger>= 0

paginated response page number, starts with 0

filtersobject
columnsArray of objects[ 1 .. 1000 ] items
sortByArray of objects[ 0 .. 1000 ] items

Sorts the result by the specified columns, in the same order as in the columns array.

totalsArray of objects[ 0 .. 1000 ] items

Dynamic Aggregation Row totals for columns. As for now, only one aggregation is supported for each column (same columnIndex) in the columns array.

curl -i -X POST \
  'https://api.observepoint.com/v3/reports/grid/{gridEntityType}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "size": 10,
    "page": 0,
    "filters": {
      "conditions": [
        {
          "negated": false,
          "operator": "string_contains",
          "filteredColumn": {
            "groupBy": false,
            "columnId": "string"
          },
          "fieldName": "id"
        }
      ],
      "conditionMatchMode": "all"
    },
    "columns": [
      {
        "groupBy": false,
        "columnId": "string"
      }
    ],
    "sortBy": [
      {
        "columnIndex": 0,
        "sortDesc": false
      }
    ],
    "totals": [
      {
        "columnIndex": 0,
        "aggregateFunction": "avg"
      }
    ]
  }'

Responses

Grid Data

Bodyapplication/json
metadataobjectrequired
metadata.​paginationobjectrequired
metadata.​pagination.​totalCountintegerrequired

Total number of items available from all result pages combined

metadata.​pagination.​totalPageCountintegerrequired

Total number of pages available

metadata.​pagination.​pageSizeintegerrequired

Page size - number of items per result page configured by size query parameter or default page size

metadata.​pagination.​currentPageSizeintegerrequired

Number of items in current result page

metadata.​pagination.​currentPageNumberintegerrequired

Current page number/ordinal

metadata.​headersArray of objectsnon-emptyrequired
metadata.​headers[].​columnobjectrequired
One of:
metadata.​headers[].​column.​groupByboolean

If true, the column is used for grouping

Default false
metadata.​headers[].​column.​columnIdstringrequired

Depends on the Grid type:

  • Audit Runs Grid: one of the AuditRunsGridColumnEnum values
  • Web Journey Runs Grid: one of the WebJourneyRunsGridColumnEnum values
  • Pages Grid: one of the PagesGridColumnEnum values
  • Cookies Grid: one of the CookiesGridColumnEnum values
  • Tags Grid: one of the TagsGridColumnEnum values
  • Tag Variables Grid: one of the TagVariablesGridColumnEnum values
  • Links Grid: one of the LinksGridColumnEnum values
  • Network Requests Grid: one of the NetworkRequestsGridColumnEnum values
  • Accessibility Issues Grid: one of the AccessibilityIssuesGridColumnEnum values
  • Browser Logs Grid: one of the BrowserLogsGridColumnEnum values
  • Rules Grid: one of the RulesGridColumnEnum values
metadata.​headers[].​totalsArray of objects

Totals for the column, available only when requested

rowsArray of objects>= 0 itemsrequired
Response
application/json
{
  "metadata": {
    "pagination": { … },
    "headers": [ … ]
  },
  "rows": [
    [ … ]
  ]
}

Get Grid Schema

Request

GET /v3/reports/grid/{gridEntityType}/schema

Returns the list of columns that area available for the specified entity type, along with each column's ID, type, supported filter operators, and supported aggreate functions

Security
API_Key
Path
gridEntityTypestringrequired

Grid entity type

Enum"web-audit-runs""web-journey-runs""pages""cookies""tags""tag-variables""links""accessibility-issues""network-requests""browser-logs"
curl -i -X GET \
  'https://api.observepoint.com/v3/reports/grid/{gridEntityType}/schema' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Grid Schema

Bodyapplication/json
columnsArray of objectsnon-emptyrequired
columns[].​columnIdstringrequired

Depends on the Grid type:

  • Audit Runs Grid: one of the AuditRunsGridColumnEnum values
  • Web Journey Runs Grid: one of the WebJourneyRunsGridColumnEnum values
  • Pages Grid: one of the PagesGridColumnEnum values
  • Cookies Grid: one of the CookiesGridColumnEnum values
  • Tags Grid: one of the TagsGridColumnEnum values
  • Tag Variables Grid: one of the TagVariablesGridColumnEnum values
  • Links Grid: one of the LinksGridColumnEnum values
  • Network Requests Grid: one of the NetworkRequestsGridColumnEnum values
  • Accessibility Issues Grid: one of the AccessibilityIssuesGridColumnEnum values
  • Browser Logs Grid: one of the BrowserLogsGridColumnEnum values
  • Rules Grid: one of the RulesGridColumnEnum values
columns[].​typestringrequired
Enum"id""entity_reference""string""number""timestamp""image"
Discriminator
columns[].​namestringrequired

Human-readable value for column, to be shown for users

columns[].​canGroupBybooleanrequired
Default true
columns[].​canPivotbooleanrequired
Default false
columns[].​supportedFilterOperatorsArray of stringsnon-emptyrequired
Items Enum"string_contains""string_contains_multi""string_regex""integer_in""integer_list_contains""number_between""date_time_between""date_time_relative""is_present""metric_alert_any"
columns[].​supportedAggregateFunctionsArray of strings>= 0 itemsrequired

If not empty, then this column can be aggregated by the functions listed in this array. Default aggregation function is the first one in the list. If empty, then this column cannot be aggregated.

Items Enum"avg""count_distinct""count_rows""max""median""min""sum""youngest""oldest""percentile_25"
columns[].​isIncludedByDefaultbooleanrequired

If true and no columns are specified in the request, this column will be included in the response.

Default false
columns[].​isNullablebooleanrequired

If true, column value can be null or empty string

Default false
Response
application/json
{
  "columns": [
    { … }
  ]
}

Create Saved Report

Request

A saved report contains information about the report, such as its name and permissions, and also the Grid API query definition that is applied when users view the report. The query definition uses the same JSON format as a Grid API request

Security
API_Key
Bodyapplication/jsonrequired
namestringnon-emptyrequired

Name of the saved report

isFavoriteboolean

Indicates if the saved report is marked as favorite by the current user

visibilitystringrequired
Enum"private""public"
queryDefinitionobjectrequired

Default Grid request body properties. Default behaviour:

  • if no page number is specified, default is 0 (the first results page)
  • if no size is specified, default is 100
  • if no filters are specified, default is to return all runs Default behaviour for exports:
  • if page and size are not specified, all available rows will be exported
queryDefinition.​sizeinteger[ 10 .. 10000 ]

how many rows to include in the paginated response

queryDefinition.​pageinteger>= 0

paginated response page number, starts with 0

queryDefinition.​filtersobject
queryDefinition.​columnsArray of objects[ 1 .. 1000 ] items
queryDefinition.​sortByArray of objects[ 0 .. 1000 ] items

Sorts the result by the specified columns, in the same order as in the columns array.

queryDefinition.​totalsArray of objects[ 0 .. 1000 ] items

Dynamic Aggregation Row totals for columns. As for now, only one aggregation is supported for each column (same columnIndex) in the columns array.

gridEntityTypestringrequired
Enum"web_audit_runs""web_journey_runs""pages""cookies""tags""tag_variables""links""accessibility_issues""network_requests""browser_logs"
displayMetadataobject

Display metadata for the saved report

curl -i -X POST \
  https://api.observepoint.com/v3/reports/grid/saved \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "isFavorite": true,
    "visibility": "private",
    "queryDefinition": {
      "size": 10,
      "page": 0,
      "filters": {
        "conditions": [
          {
            "negated": false,
            "operator": "string_contains",
            "filteredColumn": {
              "groupBy": false,
              "columnId": "string"
            },
            "fieldName": "id"
          }
        ],
        "conditionMatchMode": "all"
      },
      "columns": [
        {
          "groupBy": false,
          "columnId": "string"
        }
      ],
      "sortBy": [
        {
          "columnIndex": 0,
          "sortDesc": false
        }
      ],
      "totals": [
        {
          "columnIndex": 0,
          "aggregateFunction": "avg"
        }
      ]
    },
    "gridEntityType": "web_audit_runs",
    "displayMetadata": {}
  }'

Responses

Saved report created successfully

Bodyapplication/json
idinteger(int64)required

ID of the saved report

Response
application/json
{
  "id": 0
}

List Saved Reports

Request

GET /v3/reports/grid/saved
Security
API_Key
Query
namestring

Filter by report name, works as "saved report name contains substring" case-insensitive filter

isFavoriteboolean

Filter by favorite status

isOwnedByCurrentUserboolean

Filter by ownership status

pageinteger>= 0

Page number, starts with 0

Default 0
sizeinteger[ 10 .. 1000 ]

Number of items per page

Default 100
sortBystring

Sort by field

Enum"type""name""creator""lastViewed""sequenceNumber""visibility"
sortDescboolean

Controls sorting order

Default false
isManagedByOPboolean

Filter by managed by ObservePoint

visibilitystring

Filter by visibility status

Enum"private""public"
curl -i -X GET \
  'https://api.observepoint.com/v3/reports/grid/saved?name=string&isFavorite=true&isOwnedByCurrentUser=true&page=0&size=100&sortBy=type&sortDesc=false&isManagedByOP=true&visibility=private' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

List of saved reports

Bodyapplication/json
metadataobjectrequired

Common metadata for iterable

metadata.​paginationobjectrequired
metadata.​pagination.​totalCountintegerrequired

Total number of items available from all result pages combined

metadata.​pagination.​totalPageCountintegerrequired

Total number of pages available

metadata.​pagination.​pageSizeintegerrequired

Page size - number of items per result page configured by size query parameter or default page size

metadata.​pagination.​currentPageSizeintegerrequired

Number of items in current result page

metadata.​pagination.​currentPageNumberintegerrequired

Current page number/ordinal

reportsArray of objectsrequired
reports[].​idinteger(int64)required

ID of the saved report

reports[].​namestringrequired
reports[].​visibilitystringrequired
Enum"private""public"
reports[].​gridEntityTypestringrequired
Enum"web_audit_runs""web_journey_runs""pages""cookies""tags""tag_variables""links""accessibility_issues""network_requests""browser_logs"
reports[].​isFavoritebooleanrequired

Indicates if the saved report is marked as favorite by the current user

reports[].​createdByUserIdinteger(int64)required
reports[].​myLastViewedstring(date-time)required

Date-time in RFC3339 profile ISO 8601 format with the following additional restrictions:

  1. An uppercase T must separate the date and time portions.
  2. An uppercase Z must denote that a numeric time zone offset isn't present.

In general, these timestamp requirements are the same in AWS Step Functions - Choice Rules

Example: "2016-08-18T17:33:00Z"
reports[].​isEditablebooleanrequired

TRUE if specified saved report can be changed by the user who made the API request, FALSE otherwise

reports[].​displayMetadataobjectrequired

Display metadata for the saved report

reports[].​queryDefinitionobjectrequired

Default Grid request body properties. Default behaviour:

  • if no page number is specified, default is 0 (the first results page)
  • if no size is specified, default is 100
  • if no filters are specified, default is to return all runs Default behaviour for exports:
  • if page and size are not specified, all available rows will be exported
reports[].​queryDefinition.​sizeinteger[ 10 .. 10000 ]

how many rows to include in the paginated response

reports[].​queryDefinition.​pageinteger>= 0

paginated response page number, starts with 0

reports[].​queryDefinition.​filtersobject
reports[].​queryDefinition.​columnsArray of objects[ 1 .. 1000 ] items
reports[].​queryDefinition.​sortByArray of objects[ 0 .. 1000 ] items

Sorts the result by the specified columns, in the same order as in the columns array.

reports[].​queryDefinition.​totalsArray of objects[ 0 .. 1000 ] items

Dynamic Aggregation Row totals for columns. As for now, only one aggregation is supported for each column (same columnIndex) in the columns array.

reports[].​isSharablebooleanrequired

TRUE if specified saved report does not use cross-account grid querying mode, FALSE otherwise

reports[].​isManagedByOPbooleanrequired

TRUE if specified saved report is managed by ObservePoint, FALSE otherwise

reports[].​scheduledExportCountintegerrequired

Number of Scheduled Exports associated with this report

reports[].​sequenceNumberinteger

Ordering sequence number for ObservePoint-managed reports. Only available for ObservePoint-managed reports.

reports[].​isHighlightedboolean

Indicates if the report should be displayed in the top row. Only available for ObservePoint-managed reports.

reports[].​isExperimentalboolean

Indicates if the report is experimental and should only be visible to OpAdmin users. Only available for ObservePoint-managed reports.

reports[].​visualizationsArray of objects
Response
application/json
{
  "metadata": {
    "pagination": { … }
  },
  "reports": [
    { … }
  ]
}

Get Saved Report

Request

GET /v3/reports/grid/saved/{id}
Security
API_Key
Path
idinteger(int64)required

ID of the saved report

curl -i -X GET \
  'https://api.observepoint.com/v3/reports/grid/saved/{id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Saved report details

Bodyapplication/json
idinteger(int64)required

ID of the saved report

namestringrequired
visibilitystringrequired
Enum"private""public"
gridEntityTypestringrequired
Enum"web_audit_runs""web_journey_runs""pages""cookies""tags""tag_variables""links""accessibility_issues""network_requests""browser_logs"
isFavoritebooleanrequired

Indicates if the saved report is marked as favorite by the current user

createdByUserIdinteger(int64)required
myLastViewedstring(date-time)required

Date-time in RFC3339 profile ISO 8601 format with the following additional restrictions:

  1. An uppercase T must separate the date and time portions.
  2. An uppercase Z must denote that a numeric time zone offset isn't present.

In general, these timestamp requirements are the same in AWS Step Functions - Choice Rules

Example: "2016-08-18T17:33:00Z"
isEditablebooleanrequired

TRUE if specified saved report can be changed by the user who made the API request, FALSE otherwise

displayMetadataobjectrequired

Display metadata for the saved report

queryDefinitionobjectrequired

Default Grid request body properties. Default behaviour:

  • if no page number is specified, default is 0 (the first results page)
  • if no size is specified, default is 100
  • if no filters are specified, default is to return all runs Default behaviour for exports:
  • if page and size are not specified, all available rows will be exported
queryDefinition.​sizeinteger[ 10 .. 10000 ]

how many rows to include in the paginated response

queryDefinition.​pageinteger>= 0

paginated response page number, starts with 0

queryDefinition.​filtersobject
queryDefinition.​columnsArray of objects[ 1 .. 1000 ] items
queryDefinition.​sortByArray of objects[ 0 .. 1000 ] items

Sorts the result by the specified columns, in the same order as in the columns array.

queryDefinition.​totalsArray of objects[ 0 .. 1000 ] items

Dynamic Aggregation Row totals for columns. As for now, only one aggregation is supported for each column (same columnIndex) in the columns array.

isSharablebooleanrequired

TRUE if specified saved report does not use cross-account grid querying mode, FALSE otherwise

isManagedByOPbooleanrequired

TRUE if specified saved report is managed by ObservePoint, FALSE otherwise

scheduledExportCountintegerrequired

Number of Scheduled Exports associated with this report

sequenceNumberinteger

Ordering sequence number for ObservePoint-managed reports. Only available for ObservePoint-managed reports.

isHighlightedboolean

Indicates if the report should be displayed in the top row. Only available for ObservePoint-managed reports.

isExperimentalboolean

Indicates if the report is experimental and should only be visible to OpAdmin users. Only available for ObservePoint-managed reports.

visualizationsArray of objects
Response
application/json
{
  "id": 0,
  "name": "string",
  "visibility": "private",
  "gridEntityType": "web_audit_runs",
  "isFavorite": true,
  "createdByUserId": 0,
  "myLastViewed": "2016-08-18T17:33:00Z",
  "isEditable": true,
  "displayMetadata": {},
  "queryDefinition": {
    "size": 10,
    "page": 0,
    "filters": { … },
    "columns": [ … ],
    "sortBy": [ … ],
    "totals": [ … ]
  },
  "isSharable": true,
  "isManagedByOP": true,
  "scheduledExportCount": 0,
  "sequenceNumber": 0,
  "isHighlighted": true,
  "isExperimental": true,
  "visualizations": [
    { … }
  ]
}

Update Saved Report

Request

PUT /v3/reports/grid/saved/{id}
Security
API_Key
Path
idinteger(int64)required

ID of the saved report

Bodyapplication/jsonrequired
namestringnon-empty

Name of the saved report

isFavoriteboolean

Indicates if the saved report is marked as favorite by the current user

visibilitystring
Enum"private""public"
queryDefinitionobject

Default Grid request body properties. Default behaviour:

  • if no page number is specified, default is 0 (the first results page)
  • if no size is specified, default is 100
  • if no filters are specified, default is to return all runs Default behaviour for exports:
  • if page and size are not specified, all available rows will be exported
displayMetadataobject

Display metadata for the saved report

curl -i -X PUT \
  'https://api.observepoint.com/v3/reports/grid/saved/{id}' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "isFavorite": true,
    "visibility": "private",
    "queryDefinition": {
      "size": 10,
      "page": 0,
      "filters": {
        "conditions": [
          {
            "negated": false,
            "operator": "string_contains",
            "filteredColumn": {
              "groupBy": false,
              "columnId": "string"
            },
            "fieldName": "id"
          }
        ],
        "conditionMatchMode": "all"
      },
      "columns": [
        {
          "groupBy": false,
          "columnId": "string"
        }
      ],
      "sortBy": [
        {
          "columnIndex": 0,
          "sortDesc": false
        }
      ],
      "totals": [
        {
          "columnIndex": 0,
          "aggregateFunction": "avg"
        }
      ]
    },
    "displayMetadata": {}
  }'

Responses

Saved report updated successfully

Response
No content

Delete Saved Report

Request

DELETE /v3/reports/grid/saved/{id}
Security
API_Key
Path
idinteger(int64)required

ID of the saved report

curl -i -X DELETE \
  'https://api.observepoint.com/v3/reports/grid/saved/{id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Saved report deleted successfully

Response
No content

Favorite Saved Report

Request

POST /v3/reports/grid/saved/{id}/favorites

Mark a saved report as a "favorite" for the user to whom the API key belongs

Security
API_Key
Path
idinteger(int64)required

ID of the saved report

curl -i -X POST \
  'https://api.observepoint.com/v3/reports/grid/saved/{id}/favorites' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Saved report added to favorites successfully

Response
No content

Unfavorite Saved Report

Request

DELETE /v3/reports/grid/saved/{id}/favorites

Mark a saved report as not a favorite for the user to whom the API key belongs

Security
API_Key
Path
idinteger(int64)required

ID of the saved report

curl -i -X DELETE \
  'https://api.observepoint.com/v3/reports/grid/saved/{id}/favorites' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Saved report removed from favorites successfully

Response
No content

Start a grid data export

Request

POST /v3/reports/grid/{gridEntityType}/exports

Use this endpoint to start an export for a Grid request. After calling this endpoint, use the /v3/exports endpoint to poll the status of the export until it's finished. Then, you can download the results with the URL given by the /v3/exports endpoint.

Learn how to use the Grid export API

Security
API_Key
Path
gridEntityTypestringrequired

grid entity type

Enum"web-audit-runs""web-journey-runs""pages""cookies""tags""tag-variables""links""accessibility-issues""network-requests""browser-logs"
Bodyapplication/jsonrequired
sizeinteger[ 10 .. 10000 ]

how many rows to include in the paginated response

pageinteger>= 0

paginated response page number, starts with 0

filtersobject
columnsArray of objects[ 1 .. 1000 ] items
sortByArray of objects[ 0 .. 1000 ] items

Sorts the result by the specified columns, in the same order as in the columns array.

totalsArray of objects[ 0 .. 1000 ] items

Dynamic Aggregation Row totals for columns. As for now, only one aggregation is supported for each column (same columnIndex) in the columns array.

itemNamestring
customExportFileNamestring

Override for export file name (without file extension)

fileFormatstring

Format of the exported file

Default "xlsx"
Enum"csv""tsv""xlsx""parquet"
curl -i -X POST \
  'https://api.observepoint.com/v3/reports/grid/{gridEntityType}/exports' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "size": 10,
    "page": 0,
    "filters": {
      "conditions": [
        {
          "negated": false,
          "operator": "string_contains",
          "filteredColumn": {
            "groupBy": false,
            "columnId": "string"
          },
          "fieldName": "id"
        }
      ],
      "conditionMatchMode": "all"
    },
    "columns": [
      {
        "groupBy": false,
        "columnId": "string"
      }
    ],
    "sortBy": [
      {
        "columnIndex": 0,
        "sortDesc": false
      }
    ],
    "totals": [
      {
        "columnIndex": 0,
        "aggregateFunction": "avg"
      }
    ],
    "itemName": "string",
    "customExportFileName": "string",
    "fileFormat": "csv"
  }'

Responses

Grid export ID

Bodyapplication/json
exportIdinteger(int64)required

Unique ID of a grid export

Response
application/json
{
  "exportId": 0
}