Gets the donation summary for a race, including the fundraising goal, current total raised, and a per-charity breakdown with individual goals and totals. The per-charity response also includes processing fees paid by the race and directly paid donation profit totals, both in cents.
If no donation_period_id is provided, the current or most recent donation period is used.
Rate limit: 5 requests per hour per race. Exceeding this limit returns a 429 status code.
An example JSON response is below.
{
"race_donation_summary": {
"donation_period_id": 123,
"goal_in_cents": 500000,
"current_total_in_cents": 350000,
"charities": [
{
"charity_id": 1,
"charity_name": "Charity",
"goal_in_cents": 200000,
"current_total_in_cents": 150000,
"total_processing_fee_paid_by_race_in_cents": 4500,
"total_directly_paid_donation_profit_in_cents": 12000
},
{
"charity_id": 2,
"charity_name": "Another Charity Name",
"goal_in_cents": 300000,
"current_total_in_cents": 200000,
"total_processing_fee_paid_by_race_in_cents": 6200,
"total_directly_paid_donation_profit_in_cents": 18500
}
]
}
}
This API endpoint supports OAuth2 authentication. See the OAuth2 Developer Guide for implementation details.
Note: We may leverage OAuth2 scopes in the future to limit what access APIs require.
| Parameter | HTTP Method | Default | Description | Datatype |
|---|---|---|---|---|
api_key |
GET | API Key | string |
|
api_secret |
GET | API Secret | string |
|
rsu_api_key |
GET | API v2 key. If used, you must send the API secret in an HTTP header named X-RSU-API-SECRET. | string |
|
sp_api_key |
GET | Super partner API key. If used, you must send the API secret in an HTTP header named X-RSU-API-SECRET. | string |
|
X-RSU-API-SECRET |
HTTP Header | API v2 or super partner secret. | string |
|
Authorization |
HTTP Header | Authorization Header. If using OAuth 2.0, fill this in with `Bearer <token>`. | string |
| Parameter | HTTP Method | Default | Description | Datatype |
|---|---|---|---|---|
race_idRequired |
GET | ID of race. | uint |
|
donation_period_id |
GET | Donation period ID. Defaults to the current or most recent period. | uint |
{
"openapi": "3.0.3",
"info": {
"title": "Get Race Donation Summary",
"description": "Get donation goal, current total, and per-charity breakdown for a race.",
"version": "1.0.0",
"contact": {
"name": "RunSignup API Support",
"url": "https://runsignup.com/API",
"email": "info@runsignup.com"
}
},
"servers": [
{
"url": "https://api.runsignup.com/rest",
"description": "Production API Server"
}
],
"tags": [
{
"name": "Donations",
"description": "APIs related to Donations"
}
],
"components": {
"schemas": {
"Error": {
"type": "object",
"properties": {
"error": {
"type": "string",
"description": "Error message"
},
"details": {
"type": "object",
"description": "Additional error details",
"additionalProperties": true
}
},
"required": [
"error"
]
},
"BadRequestError": {
"allOf": [
{
"$ref": "#/components/schemas/Error"
},
{
"description": "Error indicating invalid request parameters or structure"
}
]
},
"UnauthorizedError": {
"allOf": [
{
"$ref": "#/components/schemas/Error"
},
{
"description": "Error indicating authentication failure"
}
]
},
"ForbiddenError": {
"allOf": [
{
"$ref": "#/components/schemas/Error"
},
{
"description": "Error indicating the authenticated user lacks required permissions"
}
]
},
"NotFoundError": {
"allOf": [
{
"$ref": "#/components/schemas/Error"
},
{
"description": "Error indicating the requested resource does not exist"
}
]
},
"ServerError": {
"allOf": [
{
"$ref": "#/components/schemas/Error"
},
{
"description": "Error indicating an unexpected server-side issue"
}
]
},
"V2RaceDonationsGetRaceDonationSummaryGetResponse": {
"type": "object",
"title": "Race Donation Summary",
"description": "Donation goal, current total raised, and per-charity breakdown for a race",
"properties": {
"race_donation_summary": {
"type": "object",
"description": "Race donation summary",
"properties": {
"donation_period_id": {
"type": "integer",
"description": "Donation period ID"
},
"goal_in_cents": {
"type": "integer",
"description": "Race donation goal in cents (null if no goal set)"
},
"current_total_in_cents": {
"type": "integer",
"description": "Current total raised for the race in cents"
},
"charities": {
"type": "array",
"description": "List of charities with their goals and totals",
"items": {
"type": "object",
"description": "Individual charity with goal, total, fees, and profit",
"properties": {
"charity_id": {
"type": "integer",
"description": "Charity ID"
},
"charity_name": {
"type": "string",
"description": "Charity name"
},
"goal_in_cents": {
"type": "integer",
"description": "Charity donation goal in cents (null if no goal set)"
},
"current_total_in_cents": {
"type": "integer",
"description": "Current total raised for charity in cents"
},
"total_processing_fee_paid_by_race_in_cents": {
"type": "integer",
"description": "Total processing fees paid by race for this charity in cents"
},
"total_directly_paid_donation_profit_in_cents": {
"type": "integer",
"description": "Total directly paid donation profit for this charity in cents"
}
},
"required": [
"charity_id",
"charity_name",
"current_total_in_cents",
"total_processing_fee_paid_by_race_in_cents",
"total_directly_paid_donation_profit_in_cents"
]
}
}
},
"required": [
"donation_period_id",
"current_total_in_cents",
"charities"
]
}
},
"required": [
"race_donation_summary"
],
"example": {
"race_donation_summary": {
"donation_period_id": 123,
"goal_in_cents": 500000,
"current_total_in_cents": 350000,
"charities": [
{
"charity_id": 1,
"charity_name": "Charity",
"goal_in_cents": 200000,
"current_total_in_cents": 150000,
"total_processing_fee_paid_by_race_in_cents": 4500,
"total_directly_paid_donation_profit_in_cents": 12000
},
{
"charity_id": 2,
"charity_name": "Another Charity Name",
"goal_in_cents": 300000,
"current_total_in_cents": 200000,
"total_processing_fee_paid_by_race_in_cents": 6200,
"total_directly_paid_donation_profit_in_cents": 18500
}
]
}
}
}
},
"securitySchemes": {
"oauth2": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "OAuth2 Bearer token authentication. Use the access token obtained from the OAuth2 flow in the Authorization header as: `Authorization: Bearer {access_token}`. For complete OAuth2 implementation details including endpoints, parameters, and flow specifications, see the [OAuth2 Authentication API Specification](https://runsignup.com/API/OAuth2/openapi-spec.json). For client registration and setup guidance, visit the [OAuth2 Developer Guide](https://runsignup.com/Profile/OAuth2/DeveloperGuide)."
},
"apiKey": {
"type": "apiKey",
"in": "query",
"name": "api_key",
"description": "RunSignup API Key"
},
"apiSecret": {
"type": "apiKey",
"in": "query",
"name": "api_secret",
"description": "RunSignup API Secret"
}
}
},
"paths": {
"/v2/race-donations/get-race-donation-summary.json": {
"get": {
"tags": [
"Donations"
],
"summary": "Get Race Donation Summary",
"description": "Get donation goal, current total, and per-charity breakdown for a race. This API supports OAuth2 Bearer token authentication.",
"operationId": "v2_race_donations_get_race_donation_summary_json",
"parameters": [
{
"name": "api_key",
"in": "query",
"description": "API Key",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "api_secret",
"in": "query",
"description": "API Secret",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "rsu_api_key",
"in": "query",
"description": "API v2 key. If used, you must send the API secret in an HTTP header named X-RSU-API-SECRET.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "sp_api_key",
"in": "query",
"description": "Super partner API key. If used, you must send the API secret in an HTTP header named X-RSU-API-SECRET.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "X-RSU-API-SECRET",
"in": "header",
"description": "API v2 or super partner secret.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "Authorization",
"in": "header",
"description": "Authorization Header. If using OAuth 2.0, fill this in with `Bearer <token>`.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "race_id",
"in": "query",
"description": "ID of race.",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "donation_period_id",
"in": "query",
"description": "Donation period ID. Defaults to the current or most recent period.",
"required": false,
"schema": {
"type": "integer"
}
}
],
"security": [
{
"oauth2": []
},
{
"apiKey": [],
"apiSecret": []
}
],
"responses": {
"200": {
"description": "Race Donation Summary - Donation goal, current total raised, and per-charity breakdown for a race",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/V2RaceDonationsGetRaceDonationSummaryGetResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestError"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedError"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ForbiddenError"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundError"
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ServerError"
}
}
}
}
},
"x-permissions": [
"partners",
"race_directors"
]
}
}
}
}
