# Scrape Zyte API Stats

> Query usage stats for Zyte API requests that have already been sent, including cost, request volume, response times, status codes, filters, grouping, and pagination. Use this skill whenever answering the request requires looking up recorded Zyte API usage, spend, request counts, response times, grouped stats, or filtered stats — including projecting future spend or usage when the projection explicitly extrapolates from actual recorded usage (e.g. "based on this month's usage so far, project month-end spend"). Do not use it when the user asks what a spider, job, or workload might, would, or could generate — those are hypothetical estimates with no recorded data to query, even if a spider exists in the project. For a projection to qualify, the user must explicitly reference past or current recorded usage as the basis. Also do not use for dashboard setup, documentation, configuration, or account-help questions.

- Skill: `zytedata/scrape-zyte-api-stats` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add zytedata/scrape-zyte-api-stats`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zytedata/scrape-zyte-api-stats/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: zytedata (https://skillmd.com/u/zytedata)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zytedata/scrape-zyte-api-stats

---


Query historical Zyte API usage stats using the wrapper bundled with this skill.
The bundled scripts handle auth, project lookup, and retries without exposing
API keys to the model. The stats wrapper returns the raw Stats API JSON
response; the agent is responsible for presenting that data to the user.

This skill is for querying historical usage that already happened, not for
forecasts, predictions, dashboard setup, documentation, or configuration help.

Always resolve `organization_id` by running the project lookup helper first:

1. Run the project lookup helper:

```bash
uv run --no-project "${CLAUDE_SKILL_DIR}/scripts/project_org_lookup.py"
```

2. Read the JSON status and follow this branch logic:
   - `resolved_project_with_organization`: use the returned `organization_id`
     in the stats query. If the payload also includes a `projects` list, the
     helper found multiple configured projects that all map to the same
     organization and already collapsed them safely.
   - `multiple_projects_found`: if the payload includes an `organizations`
     list, ask the user to choose among those discovered safe organization
     options, not project names and not by typing a raw organization id or
     raw project id. Present each option by `organization_id` exactly as
     returned, and keep the corresponding `selection` value privately for
     rerunning the helper with `--project`. If no `organizations` list is
     present, fall back to the listed projects.
   - `no_project_configured` or `organization_lookup_failed`: tell the user to
     use `/scrape-zyte-login` to configure a project and credentials, then retry
     the query. Name `/scrape-zyte-login` explicitly in the final user-facing
     message. Do not offer a raw organization id or raw project id as a fallback
     in these branches.

The project lookup helper reads project IDs from the standard `shub` config
(`scrapinghub.yml` in the project root, `~/.scrapinghub.yml`, or environment
variables) and calls the Zyte project endpoint to derive `organization_id`.
That is allowed for this skill. Do not read or print credential values
directly.

If the user chooses one of several discovered organization or project options,
rerun the helper with the corresponding `selection` or project value:

```bash
uv run --no-project "${CLAUDE_SKILL_DIR}/scripts/project_org_lookup.py" --project 2
```

## Wrapper

Run the wrapper with `uv`, passing query parameters as a JSON object:

```bash
uv run --no-project "${CLAUDE_SKILL_DIR}/scripts/zyte_api_stats.py" \
	--params '{"organization_id": 3}'
```

Use `${CLAUDE_SKILL_DIR}` as provided by the skill runtime. Do not prefix the
same command with an inline `CLAUDE_SKILL_DIR=...` assignment, because the
script path may be expanded before that temporary assignment applies.

Build `--params` directly from the Stats API docs. The wrapper does not
translate or validate parameter names for you.

The wrapper prints the raw Stats API JSON object. Read it and format the result
for the user yourself. Keep user-facing claims grounded in the returned JSON.
Do not assume fields exist beyond what the API returned.

When the user specifies an explicit relative window such as `last 7 days`,
`last 30 days`, or `this month`, compute one concrete UTC `start_time` /
`end_time` pair and pass those values in `--params`. Keep that workflow simple:
prefer one concise computation step when needed, and avoid repeated exploratory
shell retries.

When the user asks for `recent` usage without specifying a window, omit
`start_time` and `end_time` entirely so the API's default range applies.

If the JSON response has an empty `results` list, tell the user there was no
data for that query instead of fabricating a summary.

Use API fields such as `page`, `page_size`, and `total_result_count` to decide
whether more pages exist. If you fetch another page, keep all other query
parameters unchanged and only increment `page`.

Base claims on the wrapper output. Do not add dates, causes, feature
interpretations, or other conclusions that the wrapper did not return as data.
Do not infer caching, article size, site availability, outage causes, or other
operational explanations from cost changes, response times, or status-code
mixes unless the JSON response explicitly supports that claim.

Status codes such as `520` carry Zyte-specific semantics. Do not relabel them
unless the response or docs explicitly do so.

Both scripts resolve the Scrapy Cloud API key via `shub`. Use `--check-key`
only when you need to confirm auth is available:

```bash
uv run --no-project "${CLAUDE_SKILL_DIR}/scripts/zyte_api_stats.py" --check-key
```

If the key is missing, tell the user to run `shub login` or use the `scrape-zyte-login` skill.

## Stats API Parameters

For supported parameters, filters, grouping options, and response fields, use the official docs:

- https://docs.zyte.com/zyte-api/usage/stats.md

Use only the `Reference` section; ignore dashboard setup content.

Example with filters and grouping:

```bash
uv run --no-project "${CLAUDE_SKILL_DIR}/scripts/zyte_api_stats.py" \
	--params '{"organization_id": 3, "start_time": "2026-03-01T00:00:00Z", "end_time": "2026-03-31T23:59:59Z", "page": 1, "groupby_time": "day", "extraction_type": "article", "extraction_from": "browserHtml"}'
```