Skip to content
Screaming Data
Documentation menu

Appendix API

Usage statistics

Requests, tasks and cost per day and per endpoint for a date range.

GET
https://api.screamingdata.dev/v1/appendix/usage
Authentication
API key (HTTP Basic)
Cost
Free
Body
No request body

Overview

Returns your usage between two dates (UTC, inclusive): one row per day — days without usage included as zeros — and totals per endpoint. The dashboard chart is built from this endpoint.

The range can span at most 366 days. A date_from after date_to fails with 40501.

Cost

Free.

Request

GET /v1/appendix/usage.

Query parameters

date_from
string (date)optional

First day, YYYY-MM-DD. Defaults to 29 days before date_to.

  • Example2026-09-22
date_to
string (date)optional

Last day, YYYY-MM-DD. Defaults to today (UTC).

  • Example2026-09-24

Request example

The examples read your credentials from the API_LOGIN and API_KEY environment variables.

curl --request GET \
  --url "https://api.screamingdata.dev/v1/appendix/usage?date_from=2026-09-22&date_to=2026-09-24" \
  --user "$API_LOGIN:$API_KEY"

Response

HTTP 200. The body is the standard response envelope; check status_code at the top level and in every task.

Response example
{
  "version": "1.0.0",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.0249 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "09241251-2c4e-4a8b-9d1f-6b3e7a0c5d92",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.0114 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v1",
        "appendix",
        "usage"
      ],
      "data": {
        "api": "appendix",
        "function": "usage",
        "date_from": "2026-09-22",
        "date_to": "2026-09-24"
      },
      "result": [
        {
          "date_from": "2026-09-22",
          "date_to": "2026-09-24",
          "days": [
            {
              "date": "2026-09-22",
              "requests": 1775,
              "tasks": 3335,
              "cost": 2.425
            },
            {
              "date": "2026-09-23",
              "requests": 1853,
              "tasks": 3491,
              "cost": 2.536
            },
            {
              "date": "2026-09-24",
              "requests": 1622,
              "tasks": 3104,
              "cost": 2.314
            }
          ],
          "endpoints": [
            {
              "endpoint": "amazon/product/task_post",
              "requests": 120,
              "tasks": 4800,
              "cost": 7.2
            },
            {
              "endpoint": "amazon/product/live",
              "requests": 15,
              "tasks": 15,
              "cost": 0.06
            },
            {
              "endpoint": "amazon/product/history",
              "requests": 30,
              "tasks": 30,
              "cost": 0.015
            },
            {
              "endpoint": "amazon/product/task_get",
              "requests": 4770,
              "tasks": 4770,
              "cost": 0
            },
            {
              "endpoint": "amazon/product/tasks_ready",
              "requests": 252,
              "tasks": 252,
              "cost": 0
            },
            {
              "endpoint": "appendix/user_data",
              "requests": 63,
              "tasks": 63,
              "cost": 0
            }
          ],
          "totals": {
            "requests": 5250,
            "tasks": 9930,
            "cost": 7.275
          }
        }
      ]
    }
  ]
}

Result fields

Each element of tasks[].result is a usage object. Usage between two dates, inclusive, in UTC.

date_from
string (date)

First day of the period.

date_to
string (date)

Last day of the period.

days
array of objects

One row per day of the period, oldest first, including days without usage: date, requests, tasks, cost.

endpoints
array of objects

Totals per endpoint for the period, most expensive first: endpoint (for example amazon/product/task_post), requests, tasks, cost.

totals
object

Totals for the period: requests, tasks, cost.

Status codes

Codes this endpoint can return, at the request or task level. See Status codes for handling advice.

CodeMessageHTTPLevelWhen
20000Ok.200Request / taskThe request, or the individual task, was processed successfully.
40100Authentication failed.401RequestThe Authorization header is missing or malformed, or the login and API key do not match.
40101API key revoked.401RequestThe API key was revoked. Use another active key or create a new one.
40102Account disabled.401RequestThe account is disabled. Contact support.
40202Rate limit exceeded.429RequestToo many requests or tasks per minute for this account, or too many access requests from one IP address. The Retry-After header says how many seconds to wait.
40501Invalid field: `<name>`.400 / 200Request / taskA field has a wrong type, format or value; the message names the field, for example "Invalid field: `priority`."
50000Internal error.500RequestUnexpected server error. The request can be retried; contact support if it persists.

Related endpoints