Petrora

GUIDES · TEXAS · CONNECT

API reference

How to use the Petrora data API. Read-only JSON over Texas Railroad Commission and TexNet records, with a citation URL on every entity. What the endpoints are for, how to read the identifiers, windows, and dates, and where the machine-readable contract lives.

UPDATED OCT 29, 2026

The API serves the same records as the pages on this site, as JSON. Every response that names a well, permit, operator, county, lease, or event carries the url of its page, so anything built on the API can cite Petrora the way the site does.

This guide is about how to use the API well. The endpoint-by-endpoint contract, every parameter, every field, and a try-it client, is the interactive reference, generated from the same schemas the API validates with. The raw document is at /v1/openapi.json for SDK generators and assistants.

Basics

  • Base URL: https://api.petrora.com. Paths below are relative to it.
  • Format: JSON, UTF-8. Dates are YYYY-MM-DD, months are YYYY-MM, and timestamps are ISO 8601 in UTC.
  • Every call needs a key. Create one on your account page and send it as Authorization: Bearer pk_live_…. Calls are metered against your plan; a new account's free trial covers them.
  • The watchlist routes take your session's bearer token instead of a key, because they act on your account; the interactive reference has an Authentication box for either.
  • Beta. The API is live for every account on a free trial that starts with your first key; how to connect.
  • Errors: 400 with an error object naming the bad parameters, 404 when the record does not exist, 401 when a key or token is missing or invalid, 402 when a trial has ended or a plan has lapsed, 429 over the plan rate, 503 when the database is unreachable.
  • Paging: list endpoints take limit and offset and return total, the count before paging, so any page of any filtered list is reachable.
  • Paths are type first, then state. Records scoped to the Texas regulator sit under a tx segment: /v1/data/counties/tx/reeves, /v1/data/operators/tx/217012, /v1/data/permits/tx/918112. Wells, formations, basins, cross-section, and the map endpoints carry no state segment; a well is addressed by its full API number, which starts with the state code. The site's pages follow the same shape.

Your first three requests

curl "https://api.petrora.com/v1/data/operators/tx?days=30&limit=3"
curl "https://api.petrora.com/v1/data/operators/tx/217012"
curl "https://api.petrora.com/v1/data/wells/42-337-34003"

The first ranks operators by permits in the last 30 days. Each row carries operatorNumber and url. The second takes that number into the operator hub: registration, counties, permits by month, production, and the last year of permits, each with a well. The third opens one of those wells. Every list leads to a record and every record links onward, so the API is navigated the same way the site is.

Reading the identifiers

  • API number. Ten digits in addresses, 4233734003: the state code, the county code, and a unique number. The apiNumber field carries the eight digits the Commission stores, as a string because of the leading zero: "33734003". The endpoints also accept that form and the dashed 42-337-34003. API numbers explained.
  • Permit number. An integer. A permit has several versions as it is amended; the permit endpoint returns the current one and every version behind it.
  • Operator number. An integer, the Railroad Commission's P-5 number. A company that reorganized can hold several; Petrora does not merge them. Operator numbers and the P-5.
  • Lease id. o-10-64741: oil or gas, district, lease number. Leases are the unit Texas reports oil production by.
  • County and formation slugs. Lower-case with hyphens: reeves, san-andres. County filters on list endpoints take the name instead, case-insensitive.
  • Event id. TexNet's catalog id, such as tx2026vgingz.

Names are upper-case exactly as the Commission stores them. The site title-cases them for display; the API does not.

Reading the dates and windows

  • Permits have two dates. dateIssued is the Commission's. firstSeenAt is the day the permit first appeared in the Commission's daily files, usually a day or two later and more over weekends. The days window on the permits list runs on firstSeenAt, so "last 30 days" means what became visible in the last 30 days and nothing is missed when a file arrives late. days=all drops the window.
  • Production is reported by lease, never by well. A well record shows its leases' totals and says so. Volumes lag the reporting month by two to three months; reportedThrough on a response is the last month the statewide dump covers. A lease is in every county its completed wells are in, because lease reports leave the county blank.
  • Injection comes from H-10 reports at the last settled month and, for deep Permian disposal, from TexNet's daily volumes. Earthquakes are counted inside a county's located-permit bounding box, because the catalog carries no county.

How current the data is gives the lag for each source.

What the endpoints are for

Each group below is one tag in the interactive reference, where every parameter and field is listed.

  • Stats. Statewide counts per source, as of the last load.
  • Permits. The feed, newest first by firstSeenAt, with every filter the site offers and a CSV download; and one permit with all its versions.
  • Wells. One row per API number, filterable and downloadable; one well with permits, completions, chain of custody, lease production, tops, casing, perforations, injection, seismicity, and offset wells; a cross-section of up to eight wells' tops.
  • Counties. The leaderboard; one county's hub; the operators active there over a window or all time.
  • Map. Compact point rows for located permits, active disposal wells, and earthquakes, for plotting.
  • Fields. Every named field with a lease report; one field's counties, operators, ten-year monthly series, and last twelve months.
  • Basins. The six regions as groups of RRC districts, rolled up from the county figures; one basin's counties, operators, timeline, and latest permits.
  • Operators. The active ranking or the whole directory of 78,000 numbers; one operator's hub; its permits and wells of record; its activity in one county.
  • Formations. Named rock units from completion filings, with counties, depth ranges, and operators.
  • Leases. The list, with county, district, type, operator, and volume filters; one lease's monthly history, operator runs, wells, and a decline model when the last ten years follow one curve; the wells on a lease.
  • Water. Disposal and injection statewide and by county.
  • Earthquakes. TexNet events statewide, by county area, and one event with the injection wells within ten kilometres.
  • Account and watchlists. The signed-in user, and watchlists: saved permit searches to create, size, run live, and optionally email daily. Bearer token required.

Models are labelled

Generated text in briefing arrays is built only from counted facts in the same response. The one model the API returns is the lease decline object, and it is null unless the fit is good enough to mean something; its fields say what it is. Quote reported figures, not projected ones.

Citing

Use the url on the record. It is the canonical page for that record, it carries the same figures, and it names the sources at the bottom. If an answer built on the API gives a number with no link, the number was computed by the caller, not reported by Petrora.