API Reference

Subscribing to Endpoints

Subscribing to Endpoints

Endpoints are how data providers expose rowset data feeds on the Spartera marketplace. This guide walks you through the buyer experience — from finding an endpoint to using your API key in your own apps.

Step 1: Find an Endpoint

Browse to marketplace.spartera.com and filter for Data Feeds to see endpoints (separate from assets, which return single insights or charts).

Each endpoint listing shows:

  • The columns and types in the response
  • Sample preview rows (real data, not mock)
  • Price per request (in credits)
  • Source data domain and refresh frequency
  • Geographic and time-period coverage
  • Rate limits, if any

Step 2: Click Fetch Data

When you click Fetch Data for the first time, two things happen:

  1. The endpoint runs and returns rows directly into the marketplace UI
  2. Spartera auto-provisions an API key scoped to your company and this specific endpoint

The key appears in the right sidebar under "API Key" with a yellow warning: "Save this key now — for security, it won't be shown again."

Copy it immediately. The plain text value is shown once and is not recoverable.

Step 3: Use the Key

Your endpoint key (ep_...) lets you call the endpoint from anywhere — your own app, a script, an AI agent, or a notebook.

From your own code

curl "https://{seller_handle}.api.spartera.com/endpoints/v1/{endpoint_slug}?start=0&limit=100" \
  -H "x-api-key: ep_HeRGNo0qyvi64sRVAZI3I0GW77LpCYWi"

The {seller_handle} and {endpoint_slug} are visible in the marketplace listing's URL or in the snippet shown when you create the key.

From the marketplace UI

Just click Fetch Data again. The marketplace uses your session for authentication when fetching inside the UI — the key is for outside use.

→ See Endpoint API Reference for the full request/response shape.

Per-Request Billing

Endpoints bill per request, not per asset run. Each successful 200 response deducts the endpoint's price (in credits) from your balance.

OutcomeCharged?
200 OK with rows✅ Yes — full price
200 OK with 0 rows (filter matched nothing)✅ Yes — full price (the query ran)
4xx error (bad input, no key, rate limited)❌ No
5xx error (seller-side database problem, platform error)❌ No

You're never charged for failed requests. The spartera.billed and spartera.credits_consumed fields in every response confirm what happened.

Returning to Your Endpoint

The next time you visit the same endpoint's product page (or your app calls it), Spartera recognizes your existing key:

  • The marketplace shows a locked state: "Provisioned previously · key value hidden for security"
  • Your existing key remains active — no new key is issued
  • Subsequent fetches reuse the same key

Each buyer-company has one active endpoint key per endpoint at a time. This makes usage tracking and revocation predictable.

Lost Your Key?

If you've lost your endpoint key, rotation is the path forward — Spartera doesn't store plain text and can't recover it.

For now, contact [email protected] and we'll revoke the old key. The next time you visit the endpoint's product page, a new key is auto-provisioned and shown in plain text.

A self-serve rotation button is on the roadmap.

Multiple Endpoints, Multiple Keys

Each endpoint you subscribe to gets its own key. There's no master key that works across all your subscribed endpoints.

This is intentional:

  • Revoking access to one endpoint doesn't affect any others
  • Per-endpoint usage tracking is precise
  • Compromising one key doesn't compromise your whole account

If you need to manage many endpoint keys at scale, consider SparteraConnect — it lets AI agents discover and use endpoints via MCP without per-endpoint key management.

Pagination

Endpoints return paginated data. The default page size depends on what the seller configures, typically 100–1,000 rows. Pass start and limit to paginate:

import requests

URL = "https://{seller_handle}.api.spartera.com/endpoints/v1/{endpoint_slug}"
HEADERS = {"x-api-key": "ep_..."}

start = 0
all_rows = []

while True:
    body = requests.get(URL, headers=HEADERS, params={"start": start, "limit": 100}).json()["data"]
    all_rows.extend(body["response"]["data"])
    if not body["spartera"]["has_more"]:
        break
    start = body["spartera"]["next_start"]

print(f"Total: {len(all_rows)} rows")

Each page is billed as a separate request. A 1,000-row dataset paginated 100 at a time costs 10 requests' worth of credits.

Filtering

Most endpoints support server-side filtering via query parameters. Pass any non-hidden column name as a query param to filter rows:

# Equality
curl "https://...?team=ARI" -H "x-api-key: ep_..."

# Inequality
curl "https://...?passing_yards=>=4000" -H "x-api-key: ep_..."

Filtering before pagination reduces credit cost — fewer rows means fewer pages.

Sharing the Key With Your Team

Endpoint keys are scoped to your company, not your individual user account. You can share the key with teammates the way you'd share any internal API credential — secret manager, environment variable in CI, etc.

Anyone in your company who has the key can use it. If a team member leaves, rotate the key.

Related Pages

Updated 9 days ago

Updated 9 days ago