# /data-works/subscriptions - Proxies.sx Data Works data subscriptions Last verified: 2026-10-29 end to end against the live API (an internal test subscription on the Kavak Mexico used-car feed). Precedence: the live API wins over this file; this file wins over the HTML page at https://agents.proxies.sx/data-works/subscriptions/. A data subscription is a monthly feed of one of our house datasets (first: used-car listings with VIN from Kavak Mexico). You receive only the records that are new since your previous delivery, as CSV or JSON, by API key or in the dashboard at https://client.proxies.sx/data-works. It is billed monthly from the account balance. Our team sets it up for your account after you approve a sample and a rate (maya@proxies.sx); there is no self-serve checkout. Base URL `https://api.proxies.sx/v1`, header `X-API-Key: psx_...` (any key of the account; no extra scope). ## 1. Find your subscription ```bash curl -s https://api.proxies.sx/v1/data-works/flows -H "X-API-Key: psx_YOUR_KEY" # -> [ { "_id": "", "name": "Kavak Mexico VIN feed", "status": "active", # "health": { "lastSuccessAt": "2026-10-29T18:59:04.361Z", "recordsLastRun": 273, "lastError": null }, # "subscription": { "priceUsd": 350, "includedRecords": 5000, "overagePerRecordUsd": 0.05, # "fields": [], "requireFields": ["vin"], "startAt": "...", "periodStart": "2026-10-28T19:00:00.000Z", # "periodEnd": "2026-11-28T19:00:00.000Z", "pausedReason": null, "canceledAt": null, "sourceFlowId": "..." } } ] ``` The entry whose `subscription` is not null is your feed; keep its `_id` as ``. `health.lastSuccessAt` is your last delivery, `health.recordsLastRun` its record count. `periodEnd` is the next monthly charge. ## 2. Receive records We cut a delivery automatically once a day when new records exist. You can also cut one now: ```bash curl -s -X POST https://api.proxies.sx/v1/data-works/flows//runs -H "X-API-Key: psx_YOUR_KEY" # -> 201 { "_id": "", "trigger": "delivery", "status": "done", "slot": "", # "manifest": { "rows": 273, "fill": { "vin": 1, ... }, "until": { "at": "...", "id": "..." } } } # -> 409 {"message":"No new records since the last delivery."} (nothing is created; try after the next collector run) ``` Download it (the same file every time you ask, so a retry is safe): ```bash curl -s -o latest.csv https://api.proxies.sx/v1/data-works/flows//runs/latest/dataset.csv -H "X-API-Key: psx_YOUR_KEY" curl -s -o latest.json https://api.proxies.sx/v1/data-works/flows//runs/latest/dataset.json -H "X-API-Key: psx_YOUR_KEY" curl -s https://api.proxies.sx/v1/data-works/flows//runs -H "X-API-Key: psx_YOUR_KEY" # the last 50 deliveries, newest first curl -s -o d.csv https://api.proxies.sx/v1/data-works/flows//runs//dataset.csv -H "X-API-Key: psx_YOUR_KEY" # one delivery ``` A daily job for an agent: list runs, download every delivery whose `_id` you have not stored yet (oldest first), store the `_id`. Do not rely on `latest` alone if a day can be missed. Semantics, verified: - Only new: a delivery holds the records that became ready after the previous delivery's last record. A record is never delivered twice; a second POST right after a delivery answers 409. - VIN feeds are keyed by VIN: when a car is relisted under a new listing id, the later listing is skipped, so it is never delivered or counted twice. - A record becomes deliverable about 30 minutes after the collector run that read it (the run's settle window). Kavak Mexico is collected every 4 hours. - Each delivery holds at most what the plan still includes plus the overage your balance covers, and at most 10,000 records. - CSV and JSON carry the same records; CSV is UTF-8 with a header row. ## 3. Fields (used-car feeds) | column | type | meaning | |---|---|---| | `source` | string | marketplace key, e.g. `kavak` | | `listing_id` | string | the marketplace's listing id | | `make`, `model`, `trim` | string | as listed | | `year` | number | model year | | `mileage_km` | number | odometer, km | | `price`, `currency` | number, string | asking price at delivery, e.g. MXN | | `price_change` | null | empty in subscription deliveries (each record is delivered once, when it first becomes ready) | | `seller_type` | string | `dealer` or `private` | | `dealer_name` | string | a dealer's business name; empty for private sellers | | `city`, `state` | string | location as listed (state may be empty) | | `vin` | string | 17-character VIN (always present on a VIN feed) | | `status` | string | `active` or `removed` at delivery time | | `first_seen`, `last_seen` | ISO 8601 | when our collector first and last saw the listing | | `removed_at` | ISO 8601 or null | when the listing disappeared, if before delivery | | `listing_url` | string or null | public listing page, when known | | `image_urls` | string | space-separated image URLs | | `transmission`, `fuel_type`, `body_type` | string or null | as listed | Your subscription may deliver a subset of columns (`subscription.fields`, empty = all) and only records where `subscription.requireFields` are present. ## 4. Billing - The monthly price is charged from the account balance at the start of each period (`periodStart`); records over `includedRecords` cost `overagePerRecordUsd` each, charged at the period end. Each charge is booked once, with an invoice in the dashboard. - If the balance cannot cover a charge, new deliveries pause (earlier deliveries stay downloadable) and you get one notice. Top up; deliveries resume within 15 minutes and nothing is missed: the next delivery starts after the last record you received. - The balance never goes negative. To change or end a subscription, contact maya@proxies.sx; it cannot be paused or deleted by API. ## 5. Troubleshooting (status -> what to do) | HTTP | message | meaning | next step for an agent | |---|---|---|---| | 201 | (delivery object) | a delivery was cut | download `runs/<_id>/dataset.csv` or `.json` | | 409 | `No new records since the last delivery.` | nothing new since your last delivery | normal; try again after the next collector run (Kavak: every 4 h, plus ~30 min) or rely on the daily delivery; do not loop faster than every 15 min | | 409 | `A delivery is already being prepared.` | another request (or the daily job) is cutting one | wait 1-2 minutes, then list runs | | 409 | `This subscription has ended.` | the subscription was ended | earlier deliveries stay downloadable; contact maya@proxies.sx to restart | | 409 | `This is a data subscription: contact support to change or end it.` | pause / resume / delete were called | subscriptions are changed by support only | | 402 | `code: subscription_inactive`, `Delivery is paused until the monthly charge is paid: top up your balance.` | the monthly charge failed | a human tops up (https://client.proxies.sx/billing or https://agents.proxies.sx/quickstart/topup.md); deliveries resume within 15 min | | 402 | `code: subscription_inactive`, `This subscription is renewing; try again in a few minutes.` | the new period is being charged | retry in 15 minutes | | 402 | `code: records_used_up` | this period's included records are delivered (and, with overage, the balance covers no more) | wait for `periodEnd`, or top up when the plan has an overage rate | | 404 | `Flow not found.` | wrong ``, or a key from another account | re-list `GET /v1/data-works/flows` with a key of the subscribed account | | 404 | `Run not found.` | no delivery yet (or a wrong ``) | POST `/runs` to cut the first one, or wait for the daily delivery | | 404 | `JSON is kept for subscription deliveries; download this run as CSV.` | `dataset.json` was asked for a non-subscription flow | use `dataset.csv` | | 400 | `Invalid data format` | the id is not a 24-character hex id | copy `_id` exactly | | 401 | `Authentication required...` / `Invalid or inactive API key` | missing, mistyped or revoked key | send `X-API-Key: psx_...`; a human creates keys at https://client.proxies.sx/account | | 503 | `Data subscriptions are not enabled.` | the feature is switched off on our side | not fixable by you; contact maya@proxies.sx | Why a file might look empty or short: - `Run not found.` (404 JSON body) saved into `latest.csv`: check the HTTP status before saving (`curl -f` or `-w '%{http_code}'`). - A VIN feed skips listings without a VIN, and relisted cars already delivered. - Records appear about 30 minutes after a collector run, so a delivery cut right after a run may not include it yet; the next one will, nothing is lost. - `subscription.fields` limits columns by agreement. Support: maya@proxies.sx, https://t.me/proxies_sx. Dashboard: https://client.proxies.sx/data-works.