Reading

GET/api/v1/user/reading-goalView your reading goal.
GET/api/v1/user/reading-stats/yearView yearly reading statistics.
GET/api/v1/user/reading-stats/calendarView your monthly reading calendar.
GET/api/v1/user/reading/in-progressView your unfinished comics from the VerseDB reader.

View your reading goal.

GET/api/v1/user/reading-goal

Requires a token

Available to every authenticated member. Returns only the caller's goal.

Needs read:user or read:showcase. A read:showcase token gets the goal without notify_milestones, notify_lapses and email_updates.

Query parameters

yearinteger: UTC year; defaults to the current year.
Example: 2026

Responses

200

Success

Headers: X-RateLimit-Limit, X-RateLimit-Remaining

dataobjectrequired
data.yearintegerrequired: Example: 2026
data.targetinteger or nullrequired: Example: 12
data.read_countintegerrequired: Example: 0
data.percentnumber or nullrequired: Example: 0
data.completedbooleanrequired: Example: false
data.expected_readsinteger or nullrequired: Example: 8
data.pace_differenceinteger or nullrequired: Example: -8
data.remaininginteger or nullrequired: Example: 12
data.reads_per_weekinteger or nullrequired: Example: 1
data.editablebooleanrequired: Example: true
data.last_year_readsinteger or nullrequired: Example: 0
data.suggested_targetinteger or nullrequired: Example: 12
data.timezonestringrequired: Example: "UTC"
data.is_publicbooleanrequired: Example: false
data.notify_milestonesboolean: Left out for a read:showcase token.
Example: false
data.notify_lapsesboolean: Left out for a read:showcase token.
Example: false
data.email_updatesboolean: Left out for a read:showcase token.
Example: false
data.share_urlstring or nullrequired: Example: "https://versedb.com/user/reader/2026"
yearsarray of integersrequired

401

The request could not be processed.

messagestringrequired: Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}

403

The token holds neither read:user nor read:showcase.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

{
  "message": "Insufficient token scope."
}

429

Rate limit exceeded. This endpoint allows 300/hour (free) or 1,000/hour (PRO). Wait for the number of seconds in the Retry-After header before retrying.

Headers: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining

messagestringrequired: Example: "Too Many Attempts."

Example body, from the documented examples

{
  "message": "Too Many Attempts."
}

curl --request GET \
  'https://versedb.com/api/v1/user/reading-goal' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": {
    "year": 2026,
    "target": 12,
    "read_count": 0,
    "percent": 0,
    "completed": false,
    "expected_reads": 8,
    "pace_difference": -8,
    "remaining": 12,
    "reads_per_week": 1,
    "editable": true,
    "last_year_reads": 0,
    "suggested_target": 12,
    "timezone": "UTC",
    "is_public": false,
    "notify_milestones": false,
    "notify_lapses": false,
    "email_updates": false,
    "share_url": "https://versedb.com/user/reader/2026"
  },
  "years": [
    2026
  ]
}

View yearly reading statistics.

GET/api/v1/user/reading-stats/year

Requires a token

Pro feature. Includes goal progress, daily and monthly counts, pace, streaks, rankings and completed series for the authenticated member.

Needs read:user or read:showcase. A read:showcase token gets progress without notify_milestones, notify_lapses and email_updates.

Query parameters

yearinteger: UTC year; defaults to the current year.
Example: 2026

Responses

200

Success

Headers: X-RateLimit-Limit, X-RateLimit-Remaining

dataobjectrequired
data.progressobjectrequired
data.progress.yearintegerrequired: Example: 2026
data.progress.targetinteger or nullrequired: Example: 12
data.progress.read_countintegerrequired: Example: 0
data.progress.percentnumber or nullrequired: Example: 0
data.progress.completedbooleanrequired: Example: false
data.progress.expected_readsinteger or nullrequired: Example: 8
data.progress.pace_differenceinteger or nullrequired: Example: -8
data.progress.remaininginteger or nullrequired: Example: 12
data.progress.reads_per_weekinteger or nullrequired: Example: 1
data.progress.editablebooleanrequired: Example: true
data.progress.last_year_readsinteger or nullrequired: Example: 0
data.progress.suggested_targetinteger or nullrequired: Example: 12
data.progress.timezonestringrequired: Example: "UTC"
data.progress.is_publicbooleanrequired: Example: false
data.progress.notify_milestonesboolean: Left out for a read:showcase token.
Example: false
data.progress.notify_lapsesboolean: Left out for a read:showcase token.
Example: false
data.progress.email_updatesboolean: Left out for a read:showcase token.
Example: false
data.progress.share_urlstring or nullrequired: Example: "https://versedb.com/user/reader/2026"
data.daysarray of objectsrequired
data.days[].datestring or nullrequired: Example: "2026-01-01"
data.days[].countintegerrequired: Example: 0
data.days[].totalintegerrequired: Example: 0
data.days[].expectednumberrequired: Example: 0.03287671232876712
data.monthsobjectrequired: Reads in each month, keyed 1 to 12.
data.months.1integerrequired: Example: 0
data.months.2integerrequired: Example: 0
data.months.3integerrequired: Example: 0
data.months.4integerrequired: Example: 0
data.months.5integerrequired: Example: 0
data.months.6integerrequired: Example: 0
data.months.7integerrequired: Example: 0
data.months.8integerrequired: Example: 0
data.months.9integerrequired: Example: 0
data.months.10integerrequired: Example: 0
data.months.11integerrequired: Example: 0
data.months.12integerrequired: Example: 0
data.breakdownsobjectrequired
data.breakdowns.seriesarray of objectsrequired
data.breakdowns.series[].idintegerrequired: Example: 42
data.breakdowns.series[].namestring or nullrequired: Example: "Saga"
data.breakdowns.series[].totalintegerrequired: Example: 3
data.breakdowns.publishersarray of objectsrequired
data.breakdowns.publishers[].idintegerrequired: Example: 42
data.breakdowns.publishers[].namestring or nullrequired: Example: "Saga"
data.breakdowns.publishers[].totalintegerrequired: Example: 3
data.breakdowns.creatorsarray of objectsrequired
data.breakdowns.creators[].idintegerrequired: Example: 42
data.breakdowns.creators[].namestring or nullrequired: Example: "Saga"
data.breakdowns.creators[].totalintegerrequired: Example: 3
data.breakdowns.genresarray of objectsrequired
data.breakdowns.genres[].idintegerrequired: Example: 42
data.breakdowns.genres[].namestring or nullrequired: Example: "Saga"
data.breakdowns.genres[].totalintegerrequired: Example: 3
data.breakdowns.charactersarray of objectsrequired
data.breakdowns.characters[].idintegerrequired: Example: 42
data.breakdowns.characters[].namestring or nullrequired: Example: "Saga"
data.breakdowns.characters[].totalintegerrequired: Example: 3
data.active_daysintegerrequired: Example: 0
data.longest_streakintegerrequired: Example: 0
data.current_streakintegerrequired: Example: 0
data.projected_readsintegerrequired: Example: 0
data.projected_finishstring or nullrequired: Example: null
data.this_weekintegerrequired: Example: 0
data.this_monthintegerrequired: Example: 0
data.monthly_targetinteger or nullrequired: Example: 3
data.busiest_monthinteger or nullrequired: Example: null
data.finished_seriesarray of objectsrequired
data.finished_series[].idintegerrequired: Example: 42
data.finished_series[].namestring or nullrequired: Example: "Saga"
data.finished_series[].totalintegerrequired: Example: 54
data.finished_series[].finished_atstring or nullrequired: Example: "2026-03-01 10:00:00"
yearsarray of integersrequired

401

The request could not be processed.

messagestringrequired: Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}

403

The token holds neither read:user nor read:showcase, or the member has no Pro.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

{
  "message": "Insufficient token scope."
}

429

Rate limit exceeded. This endpoint allows 300/hour (free) or 1,000/hour (PRO). Wait for the number of seconds in the Retry-After header before retrying.

Headers: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining

messagestringrequired: Example: "Too Many Attempts."

Example body, from the documented examples

{
  "message": "Too Many Attempts."
}

curl --request GET \
  'https://versedb.com/api/v1/user/reading-stats/year' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": {
    "progress": {
      "year": 2026,
      "target": 12,
      "read_count": 0,
      "percent": 0,
      "completed": false,
      "expected_reads": 8,
      "pace_difference": -8,
      "remaining": 12,
      "reads_per_week": 1,
      "editable": true,
      "last_year_reads": 0,
      "suggested_target": 12,
      "timezone": "UTC",
      "is_public": false,
      "notify_milestones": false,
      "notify_lapses": false,
      "email_updates": false,
      "share_url": "https://versedb.com/user/reader/2026"
    },
    "days": [
      {
        "date": "2026-01-01",
        "count": 0,
        "total": 0,
        "expected": 0.03287671232876712
      }
    ],
    "months": {
      "1": 0,
      "2": 0,
      "3": 0,
      "4": 0,
      "5": 0,
      "6": 0,
      "7": 0,
      "8": 0,
      "9": 0,
      "10": 0,
      "11": 0,
      "12": 0
    },
    "breakdowns": {
      "series": [
        {
          "id": 42,
          "name": "Saga",
          "total": 3
        }
      ],
      "publishers": [
        {
          "id": 42,
          "name": "Saga",
          "total": 3
        }
      ],
      "creators": [
        {
          "id": 42,
          "name": "Saga",
          "total": 3
        }
      ],
      "genres": [
        {
          "id": 42,
          "name": "Saga",
          "total": 3
        }
      ],
      "characters": [
        {
          "id": 42,
          "name": "Saga",
          "total": 3
        }
      ]
    },
    "active_days": 0,
    "longest_streak": 0,
    "current_streak": 0,
    "projected_reads": 0,
    "projected_finish": null,
    "this_week": 0,
    "this_month": 0,
    "monthly_target": 3,
    "busiest_month": null,
    "finished_series": [
      {
        "id": 42,
        "name": "Saga",
        "total": 54,
        "finished_at": "2026-03-01 10:00:00"
      }
    ]
  },
  "years": [
    2026
  ]
}

View your monthly reading calendar.

GET/api/v1/user/reading-stats/calendar

Requires a token

Pro feature. Returns up to 60 reads per page, newest first.

Needs read:user or read:showcase; both get the same response.

Query parameters

yearinteger: UTC year; defaults to the current year.
Example: 2026
monthinteger: Month from 1 to 12; defaults to the current UTC month.
Example: 9
pageinteger: Page number, starting at 1.
Example: 1

Responses

200

Success

Headers: X-RateLimit-Limit, X-RateLimit-Remaining

dataarray of objectsrequired
data[].idintegerrequired: Example: 5678
data[].datestring or nullrequired: Example: "2026-09-14"
data[].namestring or nullrequired: Example: "Saga (2012) #1"
data[].urlstring or nullrequired: Example: "https://versedb.com/issue/5678/saga-1"
data[].coverstring or nullrequired: Example: "https://...-cover_sm.webp"
current_pageintegerrequired: Example: 1
last_pageintegerrequired: Example: 1
totalintegerrequired: Example: 0

401

The request could not be processed.

messagestringrequired: Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}

403

The token holds neither read:user nor read:showcase, or the member has no Pro.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

{
  "message": "Insufficient token scope."
}

429

Rate limit exceeded. This endpoint allows 300/hour (free) or 1,000/hour (PRO). Wait for the number of seconds in the Retry-After header before retrying.

Headers: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining

messagestringrequired: Example: "Too Many Attempts."

Example body, from the documented examples

{
  "message": "Too Many Attempts."
}

curl --request GET \
  'https://versedb.com/api/v1/user/reading-stats/calendar' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": [
    {
      "id": 5678,
      "date": "2026-09-14",
      "name": "Saga (2012) #1",
      "url": "https://versedb.com/issue/5678/saga-1",
      "cover": "https://...-cover_sm.webp"
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "total": 0
}

View your unfinished comics from the VerseDB reader.

GET/api/v1/user/reading/in-progress

Requires a token

Returns display fields only; page URLs, resume positions and private account data are excluded. Finished and unavailable books are omitted, with content preferences applied. Newest first.

Needs read:user or read:showcase; both get the same response.

Query parameters

limitinteger: Results per page (1-50); defaults to 12.
Example: 12
pageinteger: Page number, starting at 1.
Example: 1

Responses

200

Success

Headers: X-RateLimit-Limit, X-RateLimit-Remaining

dataarray of objectsrequired
data[].issueobjectrequired
data[].issue.idintegerrequired: Example: 5678
data[].issue.namestring or nullrequired: Example: "The Beginning"
data[].issue.slugstringrequired: Example: "saga-1-5678"
data[].issue.issue_numberstring or nullrequired: Example: "1"
data[].issue.cover_urlstring or nullrequired: Example: "https://...-cover_lg.webp"
data[].issue.is_nsfwbooleanrequired: Example: false
data[].issue.release_datestring or nullrequired: Example: "2012-03-14"
data[].issue.seriesobjectrequired
data[].issue.series.namestring or nullrequired: Example: "Saga"
data[].issue.series.publisher_namestring or nullrequired: Example: "Image Comics"
data[].percentnumberrequired: Example: 42.5
metaobjectrequired
meta.current_pageintegerrequired: Example: 1
meta.last_pageintegerrequired: Example: 1
meta.per_pageintegerrequired: Example: 12
meta.totalintegerrequired: Example: 0

401

Unauthenticated. The bearer token is missing, invalid, or revoked.

messagestringrequired: Example: "Unauthenticated."

Example body, from the documented examples

{
  "message": "Unauthenticated."
}

403

The token holds neither read:user nor read:showcase.

messagestringrequired: Example: "Insufficient token scope."

Example body, from the documented examples

{
  "message": "Insufficient token scope."
}

429

Rate limit exceeded. This endpoint allows 300/hour (free) or 1,000/hour (PRO). Wait for the number of seconds in the Retry-After header before retrying.

Headers: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining

messagestringrequired: Example: "Too Many Attempts."

Example body, from the documented examples

{
  "message": "Too Many Attempts."
}

curl --request GET \
  'https://versedb.com/api/v1/user/reading/in-progress' \
  --header 'Authorization: Bearer {YOUR_AUTH_KEY}' \
  --header 'Accept: application/json'

Example response 200

{
  "data": [
    {
      "issue": {
        "id": 5678,
        "name": "The Beginning",
        "slug": "saga-1-5678",
        "issue_number": "1",
        "cover_url": "https://...-cover_lg.webp",
        "is_nsfw": false,
        "release_date": "2012-03-14",
        "series": {
          "name": "Saga",
          "publisher_name": "Image Comics"
        }
      },
      "percent": 42.5
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 12,
    "total": 0
  }
}

Response headers

X-RateLimit-Limitinteger: Request quota per hour for your tier.
X-RateLimit-Remaininginteger: Requests remaining in the current window.
Retry-Afterinteger: Seconds to wait before retrying.

View your reading goal.

Query parameters

Responses

Example request

View yearly reading statistics.

Query parameters

Responses

Example request

View your monthly reading calendar.

Query parameters

Responses

Example request

View your unfinished comics from the VerseDB reader.

Query parameters

Responses

Example request

Response headers