Requests

List Requests

Changed on

List your team's individual API and app requests in a time range. Each request reports how many credits it consumed (api_credits, ui_credits), its response time (duration, in seconds), HTTP status code, endpoint type and the number of records returned. Use it to inspect per-request consumption and latency. Set group_by=search_pattern to return named summaries in groups, with an empty data list. Search patterns group requests with the same stable filters and includes credits, records, company domain sends and deduplication coverage. The date range selects when requests ran. Filter by types, exact endpoint path, origin, API key or search_pattern_key. Use credit_start_datetime/credit_end_datetime to find requests charged in that window even if they ran earlier; no request-date defaults apply in charge-window mode, and metadata.total_results reports matching requests. Unlinked charges have no request to return. Otherwise defaults to the last 5 days.

get/v0/requests/

Request

  • Base URL
    https://api.theirstack.com
  • URL
    https://api.theirstack.com/v0/requests/
  • Auth
    HTTP bearer

Query parameters

start_datetimestring date-time nullable

Start datetime in ISO format (e.g., 2023-01-01T00:00:00). Defaults to 5 days ago.

end_datetimestring date-time nullable

End datetime in ISO format (e.g., 2023-01-01T23:59:59). Defaults to now.

request_id_orinteger[] nullable

Return only these request ids. When set, the date range is ignored, so a single request can be addressed without knowing when it ran.

pageinteger

The page number of the results

limitinteger

Return at most this many results

group_by'search_pattern' nullable
search_pattern_keystring nullable

Only requests from this search pattern key.

credit_start_datetimestring date-time nullable

Start of the charge-date window (inclusive), independent of when requests ran.

credit_end_datetimestring date-time nullable

End of the charge-date window (inclusive).

credit_typesRequestCreditType[] nullable

Only requests with positive charges of these types in the charge window: api or ui (Company credits). Returned credit totals use the same window and selected types.

is_origin_appboolean nullable

Filter by origin app or api

origin'api' | 'app' | 'web' | 'mcp' | 'admin_mcp'

Filter by request origin (api, app, web, mcp)

api_key_idstring uuid nullable

Filter by API key id

typesRequestType[] nullable

Filter by search type.

endpointsstring[] nullable

Match any exact request URL path; unassigned selects charges without a recorded endpoint. Intersects the singular endpoint filter.

status_codesinteger[] nullable

Match any HTTP response status code.

endpointstring nullable

Exact request URL path, e.g. /v1/jobs/search; host and query string are ignored.

min_credits_consumedinteger nullable

Only requests whose total (api + ui) credits consumed are at least this.

max_credits_consumedinteger nullable

Only requests whose total (api + ui) credits consumed are at most this.

timezonestring

IANA timezone, such as Europe/Madrid.

Response

Successful Response

Example response

{
  "metadata": {
    "total_results": 2034
  }
}

Changes

  • 1dcfebfc40baRevision changes
    • info

      added the optional property // to the response with the status

  • 16937613a4ecRevision changes
    • warning

      deleted the query request parameter campaign_key

    • info

      added the new optional query request parameter search_pattern_key

    • info

      added the optional property // to the response with the status