Documentation

Quota management

Pl@ntNet API usage is subject to quota.

General information

Although a few ones are unlimited in usage (ex: /languages, /projects), most routes of Pl@ntNet API are subject to quota.

Quotas are defined per user, per request category, per day. This means that each user account is granted only a certain number of requests every day, for a given request type. When this number is exceeded, you have to wait until next day at 00:00:00 UTC to see your quota reset.

A request type is a set of routes that are meant to be used together, or provide the same service. For example, /v2/identify routes are of type identify; all /dwc routes are of type dwc.

Quota information is returned through HTTP headers for each request concerned.

Dedicated routes allow to follow your quota.

Routes list

  • /v2/quota
    • Returns the daily quota you are granted, for each request type.
  • /v2/quota/daily
    • Returns your request count and remaining quota by request type, for the current day.
  • /v2/quota/history
    • Returns your request count and remaining quota by request type, for each day since the start of your contract.

See OpenAPI doc for details.

Headers list

RateLimit-Policy

Returns the definition of the quota policy applied to your request.

  • q is the amount of requests granted, for the current request category (ex: 'identify')
  • w is the time window in seconds, always 86400 for a daily quota
  • pk is the Partition Key, describing the combination of (user account & request type), for the which the quota is granted

ex: RateLimit-Policy: "dailyQuota";q=2000;w=86400;pk=:MjEyNjQxMDM3MDAtdm90ZXM=:

You are granted 2000 requests per day for the current request type.

See draft-ietf-httpapi-ratelimit-headers-08

RateLimit

Returns the state of the quota applied to your request.

  • r is the amount of requests remaining, for the current request category (ex: 'identify')
  • t is the number of seconds before the time window resets (next day at 00:00:00 UTC)
  • pk is the Partition Key, describing the combination of (user account & request type), for the which the quota is granted

ex: RateLimit: "dailyQuota";r=1999;t=32934;pk=:MjEyNjQxMDM3MDAtdm90ZXM=:

You have 1999 requests remaining today for the current request type.

See draft-ietf-httpapi-ratelimit-headers-08

Retry-After

UTC date string of daily quota renewal (next day at 00:00:00 UTC), RFC 7231 compliant. Returned along with HTTP 429 error in case of exceeded quota.

ex: Retry-After: Tue, 18 Mar 2025 00:00:00 GMT

See RFC 7231

cURL examples

GET /v2/quota

curl 'https://my-api.plantnet.org/v2/quota?api-key=YOUR_API_KEY'

{
  "quota": {
    "identify": 5000,
    "dwc": 200,
    (…)
  }
}

GET /v2/quota/daily

curl 'https://my-api.plantnet.org/v2/quota/daily?api-key=YOUR_API_KEY'

{
  "day": "2025-02-04",
  "quota": {
    "identify": {
      "count": 3362,
      "total": 5000,
      "remaining": 1638
    },
    "dwc": {
      "count": 0,
      "total": 200,
      "remaining": 200
    },
    (…)
  }
}

GET /v2/quota/history

For contractualized accounts only; see contract.