Report Querying and Results: Commonalities

All API queries for “Reports” are HTTP GETs with optional query strings that allow you to narrow down the scope of the request and/or select which of the many matches to actually return. The following table lists the optional query string parameters that you can use with any report request. The meaning of “date” referred to in the date restrictions will depend on what API call is being executed.

Keyword Date Type Description
after_date DATETIME Return only matches dated after this date time. Format “YYYY-MM-DD HH:MM:SS” in GMT.
before_date DATETIME Return only matches dated before this date time. Return only matches dated after this date time.
first_row Integer (Default value 0). All of the matches are sorted and numbered starting from 0. E.g. if you have 100,000 matches, these are rows 0 through 99,999. If you specify a first_row, then the returned matches will be those rows starting from that row. E.g. without a specification (or if you specify 0), you might get rows 0 through 49,999. In your next request you might specify first_row=50000 to get rows 50000 to 99,999.
from_date DATETIME Return only matches dated on or after this date time. Format “YYYY-MM-DD HH:MM:SS” in GMT.
matches Integer (Default value 50000). You can set matches to any value from 0 to 50000. This sets the maximum number of matches that will be returned in response to your request. Note that if the response size starts to exceed 50MB, then the response can still include fewer than your “matches” number, to keep the response size reasonable. If you specify “0” here, then no matches will be returned; however, you will still get the information on the number of matches that there were.
through_date DATETIME Return only matches dated before or on this date time. Format “YYYY-MM-DD HH:MM:SS” in GMT.

Additional query string parameters, specific to specific reports, are described in the documentation for those API endpoints.

The response to a successful Report request will be a JSON object with a data section that is an associated array. Among other endpoint-specific data, it will contain a number of standard keyword data fields:

Keyword Date Type Description
first Integer The index of the first row that was returned. E.g. this should match the “first_row” parameter specified in the request.
header Array Array that includes the column headings for all of the matches returned.
matches_returned Integer The number of matching rows returned in the “rows” array.
matches_total Integer The number of rows matching your request. Note that this can be larger than the number of rows returned.
rows Array Array of data for all matches returned. This array contains one element for each returned match. Each element is itself an array. Each field in the match arrays corresponds to the respective field in the “header” array. E.g. if the 1st element in the “header” array is “user_id”, then the 1st element in a match data array will be the integer user ID number, etc.

Note: A report query could match zero to millions of rows, depending on the report and the context. Returning millions of rows in response to a single request is not feasible as the download would be absolutely huge. Report result sets are limited to at most 50,000 matches or about 50MB of data (whichever occurs first). If your query matches more than that, then only a subset of matches is returned. We recommend using the query parameters and the result data to page through your results as needed. We also recommend using the data restriction options to make your requests as specific as possible – this will make them faster and allow them to return smaller result sets.

< API Overview Page