# Horse Racing Pulse API (`0xgollum/horse-racing-pulse-api`) Actor

Live PMU horse-racing odds as an always-on HTTP API (Server Actor): GET /races for every race open for betting with odds per runner, GET /movers for steamers and drifters over the last N minutes. 19 filters, answers in milliseconds from a once-a-minute cache.

- **URL**: https://apify.com/0xgollum/horse-racing-pulse-api.md
- **Developed by:** [0xGollum](https://apify.com/0xgollum) (community)
- **Categories:** Automation, Developer tools
- **Features:** Limited permissions, Single-tenant, Server interface
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 api requests

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Horse Racing Pulse API — live PMU odds in one HTTP call

Your bot needs the odds of the 14:15 at Vincennes **now**, not after a 2-minute scraper run. This Server Actor stays awake and answers from a cache that refreshes every race still open for betting **once a minute**: a GET returns live odds per runner in milliseconds, and `/movers` tells you which horses the money is moving on.

### What a call returns

`GET /movers?countries=FRA&window_minutes=10`

```json
{
  "updated_at": "2026-11-11T07:45:24+00:00",
  "window_minutes_used": 10.0,
  "mover_count": 1,
  "movers": [{
    "signal": "steamer", "trigger": "relative",
    "hippodrome": "LYON LA SOIE", "race_code": "R4C2", "race_name": "OURASI",
    "horse_num": 6, "horse_name": "JUAN LES PINS",
    "current_cote": 16.0, "previous_prob_pct": 2.5, "current_prob_pct": 6.25,
    "prob_change_pct": 3.75, "relative_change_pct": 150.0
  }]
}
```

`GET /races` returns every open race (venue, `R4C2` code, start time in Unix ms, discipline, distance, prize, runners) with a `runners_list` sorted favourite first: number, name, jockey/driver, decimal odds, implied probability.

### Endpoints

| Endpoint | What you get | Billed |
|---|---|---|
| `GET /races` | Races open for betting, odds per runner | 1 `api-request` |
| `GET /movers` | Steamers and drifters over the last `window_minutes` (1-90, default 10) | 1 `api-request` |
| `GET /health` | Cache age, runners tracked | free |
| `GET /` | This list of endpoints | free |

A request that fails (warming up, bad parameter) is **never billed**.

`/movers` parameters: `window_minutes`, `threshold_pct` (implied-probability points, default 5), `relative_pct` (relative change, default 30 %; catches the 50/1 → 20/1 outsider that only moves 3 points), `limit` (default 25). The server keeps 90 minutes of snapshots in memory, so you don't need to schedule anything to see movement.

### Filters (query parameters, same as Horse Racing Pulse)

Lists are comma-separated: `?countries=FRA&disciplines=PLAT,HAIE&meetings=CHANTILLY`.

`countries`, `meetings` (partial, accent-insensitive), `disciplines` (PLAT, HAIE, STEEPLECHASE, ATTELE, MONTE, CROSS), `categories` (HANDICAP, GROUPE_I…), `surfaces`, `going`, `age_conditions`, `sex_conditions`, `track_directions`, `min_distance_m` / `max_distance_m`, `min_prize_eur` / `max_prize_eur`, `min_runners` / `max_runners`, `start_after` / `start_before` (HH:MM, `filter_timezone` default Europe/Paris), `min_odds` / `max_odds` (runner level), `max_races` (`/races`, default 20).

### How to call it

Copy the URL from the **Server** tab of this Actor and send your Apify token in a header:

```bash
curl -H "Authorization: Bearer $APIFY_TOKEN" \
  "https://<server-url>/movers?countries=FRA&window_minutes=15"
```

```python
import httpx
r = httpx.get("https://<server-url>/races", params={"disciplines": "PLAT", "max_races": 5},
              headers={"Authorization": f"Bearer {token}"})
```

The first call after a quiet period wakes the server (a few seconds), then answers are immediate. `/movers` needs a few minutes of history after a wake-up: until then it says so and uses the longest window available.

### Classic run

Started from the Input tab like any Actor, it takes one snapshot of the open races and writes it to the dataset (same filters). Use it to test the filters before wiring the API.

### Data source and limits

Odds come from PMU's public programme (French tracks plus the foreign tracks PMU takes bets on). Pari-mutuel odds float with the pool until the off, so morning odds move a lot on thin pools: raise `threshold_pct` or narrow `start_after` / `start_before` to focus on races about to start. Races that have started or closed disappear from the cache. Not affiliated with PMU. Odds are informational, not betting advice.

Need scheduled runs with history kept between runs and hidden form patterns per horse? See **Horse Racing Pulse** (same filters, batch mode).

# Changelog

This Actor's version history is a separate document: https://apify.com/0xgollum/horse-racing-pulse-api/changelog.md

# Actor input Schema

## `max_races` (type: `integer`):

How many soonest-starting races still open for betting to scan per run.

## `countries` (type: `array`):

Only these countries. PMU 3-letter codes: FRA, GBR, IRL, SWE, ESP, HKG, USA... Empty = all.

## `meetings` (type: `array`):

Only these racecourses, e.g. CHANTILLY, LONGCHAMP, VINCENNES, ASCOT. Partial and case/accent-insensitive (LONGCHAMP matches PARISLONGCHAMP). Empty = all.

## `disciplines` (type: `array`):

PLAT (flat), ATTELE (harness trot), MONTE (ridden trot), HAIE (hurdles), STEEPLECHASE, CROSS. English also accepted: FLAT, HURDLE, CHASE, TROT. Empty = all.

## `categories` (type: `array`):

e.g. HANDICAP (matches every handicap variant), COURSE_A_CONDITIONS, A_RECLAMER (claimers), GROUPE_I / GROUPE_II / GROUPE_III, AMATEURS, APPRENTIS, AUTOSTART, EUROPEENNE, INTERNATIONALE, NATIONALE. A word matches any category containing it; GROUPE_I does not match GROUPE_II. Empty = all.

## `surfaces` (type: `array`):

HERBE (turf; GAZON/TURF accepted), PSF (all-weather), SABLE (sand/dirt), POUZZOLANE. Empty = all.

## `going` (type: `array`):

Official going, e.g. Bon, Bon souple, Souple, Très souple, Lourd, Léger, Bon léger, PSF RAPIDE, PSF STANDARD (case/accent-insensitive, exact label). Empty = all.

## `age_conditions` (type: `array`):

e.g. DEUX_ANS, TROIS_ANS, TROIS_ANS_ET_PLUS, QUATRE_ANS, QUATRE_ANS_ET_PLUS, CINQ_ANS_ET_PLUS. Exact match. Empty = all.

## `sex_conditions` (type: `array`):

TOUS_CHEVAUX, FEMELLES (fillies/mares), MALES, MALES_ET_HONGRES, FEMELLES_ET_MALES. Empty = all.

## `track_directions` (type: `array`):

CORDE_DROITE (right-handed), CORDE_GAUCHE (left-handed), LIGNE_DROITE (straight). Empty = all.

## `min_distance_m` (type: `integer`):

Only races of at least this distance, in metres (1 furlong ≈ 201 m).

## `max_distance_m` (type: `integer`):

Only races up to this distance, in metres.

## `min_prize_eur` (type: `integer`):

Only races whose total prize money is at least this amount.

## `max_prize_eur` (type: `integer`):

Only races whose total prize money is at most this amount.

## `min_runners` (type: `integer`):

Skip small fields: only races with at least this many declared runners.

## `max_runners` (type: `integer`):

Only races with at most this many declared runners.

## `start_after` (type: `string`):

Only races starting at or after this time (see filter_timezone), e.g. 13:30.

## `start_before` (type: `string`):

Only races starting at or before this time, e.g. 18:00. A window across midnight works (22:00 → 02:00).

## `filter_timezone` (type: `string`):

IANA timezone for start_after/start_before, e.g. Europe/Paris (default), Europe/London, Asia/Tokyo.

## `min_odds` (type: `number`):

Only horses currently at these decimal odds or longer, e.g. 5 to skip short favourites. Applied to every row type.

## `max_odds` (type: `number`):

Only horses currently at these decimal odds or shorter, e.g. 20 to skip long shots. Applied to every row type.

## Actor input object example

```json
{
  "max_races": 20,
  "countries": [],
  "meetings": [],
  "disciplines": [],
  "categories": [],
  "surfaces": [],
  "going": [],
  "age_conditions": [],
  "sex_conditions": [],
  "track_directions": []
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("0xgollum/horse-racing-pulse-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("0xgollum/horse-racing-pulse-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call 0xgollum/horse-racing-pulse-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,0xgollum/horse-racing-pulse-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/YHBHOjlLmGIf0lFLw/builds/N2G1Vm8AXZPwdEKn6/openapi.json
