Using Counters in Python

Send counter increments, decrements, and reads from a Python application using the TapTally HTTP API.

Overview

Every counter operation in TapTally is a plain HTTP request. This page shows how to fire increments, decrements, and reads from Python — no SDK required.

Prerequisites

A TapTally instance with a known base URL (e.g. http://localhost:8080)
An API key with at least write:counters scope — see Counter API Keys for how to create one
A counter that already exists (namespace + key pair) — see Counters
The requests library: pip install requests

API at a glance

POST /v1/counters/{namespace}/{key}/incr
POST /v1/counters/{namespace}/{key}/decr
GET  /v1/counters/{namespace}/{key}

The request body for increment/decrement is optional. Omit it to step by 1, or pass { "by": N } to step by any integer:

{ "by": 5 }

Every response returns a counter object:

{
  "namespace": "blog",
  "key":       "post-views",
  "value":     42,
  "updated_at": "2025-07-07T10:30:00Z"
}

The X-API-Key header is required on every authenticated request.

Example

import os
import requests

BASE_URL = os.getenv("TAPTALLY_URL", "http://localhost:8080")
API_KEY  = os.getenv("TAPTALLY_API_KEY")

HEADERS = {
    "X-API-Key":    API_KEY,
    "Content-Type": "application/json",
}


def increment(namespace: str, key: str, by: int = 1) -> dict:
    url = f"{BASE_URL}/v1/counters/{namespace}/{key}/incr"
    resp = requests.post(url, json={"by": by}, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()


def decrement(namespace: str, key: str, by: int = 1) -> dict:
    url = f"{BASE_URL}/v1/counters/{namespace}/{key}/decr"
    resp = requests.post(url, json={"by": by}, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()


def get_counter(namespace: str, key: str) -> dict:
    url = f"{BASE_URL}/v1/counters/{namespace}/{key}"
    resp = requests.get(url, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()


# Example usage
counter = increment("blog", "post-views")
print("New value:", counter["value"])

Error reference

Status	Meaning
`401`	Missing or invalid API key
`403`	Key exists but lacks `write:counters` scope, or the key is scoped to a different counter
`404`	Counter (`namespace` / `key` pair) does not exist — create it first via the UI or the API
`400`	Malformed request body

Call resp.raise_for_status() after every request to surface errors early rather than silently dropping events.

Where to next

Using Counters in Node.js — Node.js example
Using Counters in Go — Go example
Counter API Keys — create and scope API keys
Dashboards & Analytics — visualise the data you are sending

Found an issue in the docs? Open an issue on GitHub.