Count answers within a verse range

Get per-verse counts of published questions within a range. Non-Arabic languages resolve to English upstream. This endpoint preserves the internal range-limit behavior exactly: it rejects ranges where to_index - from_index > 30.

Query Parameters

from string required

Starting ayah key in chapter:verse format.

to string required

Ending ayah key in chapter:verse format.

language string

Default value: en

Requested language. ar returns Arabic; every other language resolves to English upstream.

Responses

• 200
• 400
• 401
• 403
• 422
• 429
• 500
• 502
• 503
• 504

---

Successful response

application/json

Schema

Example (from schema)

default_success

range_with_answer_counts

range_with_no_answers

---

Schema

property name* AnswersCountWithinRangeEntry

types object required

Per-question-type counts for the verse.

property name* integer

total integer required

Total number of questions touching the verse.

{}

Successful response

{
  "2:255": {
    "types": {
      "CLARIFICATION": 1,
      "TAFSIR": 1
    },
    "total": 2
  },
  "2:256": {
    "types": {
      "TAFSIR": 1
    },
    "total": 1
  }
}

Answer counts grouped by ayah and type

{
  "2:255": {
    "types": {
      "CLARIFICATION": 1,
      "TAFSIR": 1
    },
    "total": 2
  },
  "2:256": {
    "types": {
      "TAFSIR": 1
    },
    "total": 1
  }
}

Verse range with no answers

{
  "1:1": {
    "types": {},
    "total": 0
  },
  "1:2": {
    "types": {},
    "total": 0
  }
}

Invalid parameter. Returned for malformed ayah keys, invalid ranges, or invalid pagination values.

application/json

Schema

Example (from schema)

Example

---

Schema

status integer required
error object required
code string required
Possible values: [INVALID_PARAMETER, NOT_FOUND]
message string required
details object
property name* any

{
  "status": 0,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "string",
    "details": {}
  }
}

{
  "status": 400,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid ayah_key format. Expected format: chapter:verse (e.g., 12:12)",
    "details": {
      "parameter": "ayah_key",
      "provided": "2-255",
      "expected": "12:12"
    }
  }
}

Will be returned when the request is unauthorized.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string

Possible values: [gateway_timeout, service_unavailable, bad_gateway, internal_server_error, unprocessable_entity, not_found, forbidden, unauthorized, invalid_request, invalid_token, insufficient_scope, service_error, invalid_path, rate_limit_exceeded]

success boolean

{
  "message": "string",
  "type": "gateway_timeout",
  "success": true
}

{
  "message": "The request requires user authentication",
  "type": "unauthorized",
  "success": false
}

Forbidden error. Can either be due to access token not being passed, having been expired or the caller trying to access a resource without enough permissions.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string

Possible values: [gateway_timeout, service_unavailable, bad_gateway, internal_server_error, unprocessable_entity, not_found, forbidden, unauthorized, invalid_request, invalid_token, insufficient_scope, service_error, invalid_path, rate_limit_exceeded]

success boolean

{
  "message": "string",
  "type": "gateway_timeout",
  "success": true
}

{
  "message": "The server understood the request, but refuses to authorize it",
  "type": "forbidden",
  "success": false
}

Validation Error. The request includes one or more invalid params. Please check the request params and try again.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string

Possible values: [gateway_timeout, service_unavailable, bad_gateway, internal_server_error, unprocessable_entity, not_found, forbidden, unauthorized, invalid_request, invalid_token, insufficient_scope, service_error, invalid_path, rate_limit_exceeded]

success boolean

{
  "message": "string",
  "type": "gateway_timeout",
  "success": true
}

{
  "message": "The request was well-formed but was unable to be followed due to semantic errors",
  "type": "unprocessable_entity",
  "success": false
}

Rate-limit exceeded

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string

Possible values: [gateway_timeout, service_unavailable, bad_gateway, internal_server_error, unprocessable_entity, not_found, forbidden, unauthorized, invalid_request, invalid_token, insufficient_scope, service_error, invalid_path, rate_limit_exceeded]

success boolean

{
  "message": "string",
  "type": "gateway_timeout",
  "success": true
}

{
  "message": "Too many requests, please try again later",
  "type": "rate_limit_exceeded",
  "success": false
}

Server Error. Something went wrong, try again later.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string

Possible values: [gateway_timeout, service_unavailable, bad_gateway, internal_server_error, unprocessable_entity, not_found, forbidden, unauthorized, invalid_request, invalid_token, insufficient_scope, service_error, invalid_path, rate_limit_exceeded]

success boolean

{
  "message": "string",
  "type": "gateway_timeout",
  "success": true
}

{
  "message": "The server encountered an internal error and was unable to complete your request",
  "type": "internal_server_error",
  "success": false
}

Bad Gateway

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string

Possible values: [gateway_timeout, service_unavailable, bad_gateway, internal_server_error, unprocessable_entity, not_found, forbidden, unauthorized, invalid_request, invalid_token, insufficient_scope, service_error, invalid_path, rate_limit_exceeded]

success boolean

{
  "message": "string",
  "type": "gateway_timeout",
  "success": true
}

{
  "message": "The server was acting as a gateway or proxy and received an invalid response from the upstream server",
  "type": "bad_gateway",
  "success": false
}

Service Unavailable

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string

Possible values: [gateway_timeout, service_unavailable, bad_gateway, internal_server_error, unprocessable_entity, not_found, forbidden, unauthorized, invalid_request, invalid_token, insufficient_scope, service_error, invalid_path, rate_limit_exceeded]

success boolean

{
  "message": "string",
  "type": "gateway_timeout",
  "success": true
}

{
  "message": "The server is currently unable to handle the request due to a temporary overload or scheduled maintenance",
  "type": "service_unavailable",
  "success": false
}

Gateway Timeout

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string

Possible values: [gateway_timeout, service_unavailable, bad_gateway, internal_server_error, unprocessable_entity, not_found, forbidden, unauthorized, invalid_request, invalid_token, insufficient_scope, service_error, invalid_path, rate_limit_exceeded]

success boolean

{
  "message": "string",
  "type": "gateway_timeout",
  "success": true
}

{
  "message": "The server was acting as a gateway or proxy and did not receive a timely response from the upstream server",
  "type": "gateway_timeout",
  "success": false
}

Loading...