Using MMDC from scripts and AI agents¶
This page is for code that calls MMDC without a person at the browser: scripts, notebooks run in batch, pipelines and AI agents. It collects the rules such a client should follow and one recipe per task. The Python SDK follows these rules for you; the raw HTTP section shows them for other languages.
Rules in short
- Positions are ICRS right ascension and declination in degrees.
- Resolve a source name to a position first; the SED API takes positions, not names.
- Identify your client: the SDK does, and
MMDC(app="your-project")names your project. Raw HTTP must send anX-MMDC-Clientheader, or modeling requests get HTTP 426. - An SED request reuses any job within 2″. Do not send
refreshroutinely. - Run at most 2 jobs at a time, respect
Retry-After, and wait withPrefer: wait=25instead of polling in a tight loop. - Undated catalogue values carry MJD 50000; they are not observations from 1995.
- Cite Sahakyan et al. 2024, AJ, 168, 289 (doi:10.3847/1538-3881/ad8231). MMDC data are licensed under CC BY 4.0.
Install and identify¶
Every SDK request carries User-Agent: astro-mmdc/<version>. app adds an X-MMDC-Client
header with your project name, which keeps your jobs apart from other SDK users behind the same
IP address. An api_key (sent as X-API-Key) gives a higher limit on concurrent fits; see
Identifying your application and users.
Resolve a name to a position¶
MMDC's own name lookup is client.catalogs.autocomplete(query). It returns up to 40 catalogue
entries with name, ra, dec (degrees) and refcatalog, or an empty list. A name matches as a
substring, ignoring case and spaces, and the entries come in no particular order, so pick the one
whose name you asked for instead of taking the first:
hits = client.catalogs.autocomplete("Mrk 421")
# [CatalogEntry(name='MRK421', ra=166.1138, dec=38.20883, refcatalog='INTREFCAT')]
want = "mrk421"
match = next((h for h in hits if h.name.replace(" ", "").lower() == want), None)
if match is None:
raise SystemExit(f"no exact match: {[h.name for h in hits]}")
ra, dec = match.ra, match.dec
A name not in the catalogue is resolved with NED, then SIMBAD (this can take up to a minute), but
only while your IP is under 100 unresolved names per hour; past that an unknown name returns [].
Behind client.for_user() all your end users share your server's IP. The query can also be a
position, "RA DEC" or "RA,DEC" in degrees (out of range gives HTTP 400), or a single number,
searched as RA only.
An interactive caller with its own fallback (a chat turn, a search box) can cap the wait, retries
included. Each attempt is limited to the time left, so the call returns in about timeout seconds
(connect and read are separate phases, so the worst case is a bit under twice that):
import httpx
from astro_mmdc import MMDCError
try:
hits = client.catalogs.autocomplete("Mrk 421", timeout=10)
except (httpx.TransportError, MMDCError): # timeouts, or a 503/504 at the deadline
hits = []
timeout=None, the default, waits up to 75 s per request (past the server proxy's 60 s) and
150 s in all; unlike client.sed, it does not mean wait forever.
Over raw HTTP it is POST https://mmdc.am/api/autocomplete/ with {"query": "<name>"}, answering
{"results": [{"name", "ra", "dec", "refcatalog"}, ...]}:
import httpx
r = httpx.post("https://mmdc.am/api/autocomplete/", json={"query": "Mrk 421"},
headers={"X-MMDC-Client": "my-pipeline"})
hits = r.json()["results"] # [{"name": "MRK421", "ra": 166.1138, "dec": 38.20883, ...}]
match = next(h for h in hits if h["name"].replace(" ", "").lower() == "mrk421")
ra, dec = match["ra"], match["dec"]
A query can match several entries (3C 273 gives two); pick one, or ask the user. Astropy's
resolver (SIMBAD/NED/VizieR) works as well, and the SDK accepts the SkyCoord directly:
from astropy.coordinates import SkyCoord
coord = SkyCoord.from_name("Mrk 421")
sed = client.sed.get(coord, name="Mrk 421")
SED of a source¶
from astro_mmdc import SEDJobFailed, SEDNoData, SEDTimeoutError
try:
sed = client.sed.get(ra=166.113808, dec=38.208833, name="Mrk 421")
except SEDNoData:
raise SystemExit("no points at this position") # the pipeline ran and found nothing
except SEDJobFailed as exc:
raise SystemExit(f"failed: {exc.code}, retry after {exc.retry_after_s} s")
except SEDTimeoutError as exc:
sed = client.sed.fetch(exc.id) # the job keeps running on the server; pick it up later
print(sed.source.redshift, sed.points)
sed.freq_hz, sed.nufnu, sed.nufnu_err, sed.is_ul # columns, one entry per point
sed.mjd_start, sed.mjd_end, sed.undated, sed.catalog
freq_hz is in Hz, nufnu and nufnu_err in erg cm⁻² s⁻¹; for an upper limit (is_ul)
nufnu is the limit. Most positions are cached and answer in one request; a new position runs
about 60 catalogues and takes up to a few minutes. get() waits up to timeout (900 s by
default).
Filter by time on the client or on the server, then save:
recent = sed.between(58000, 58400) # midpoint in [58000, 58400]; undated points dropped
sed = client.sed.get(ra=166.113808, dec=38.208833, mjd_start=58000, mjd_end=58400)
recent.to_csv("mrk421.csv") # freq_hz,nufnu,nufnu_err,is_ul,mjd_start,mjd_end,catalog,band,reference
Undated catalogue values have mjd_start = mjd_end = 50000 and undated True. A time window
drops them unless you pass undated=True.
For many sources use client.sed.get_many(...), which runs 2 at a time by default:
seds = client.sed.get_many([(166.113808, 38.208833, "Mrk 421"), (187.2779, 2.0524, "3C 273")],
return_exceptions=True)
More in the SED data guide.
Light curve¶
Light-curve rows (Fermi-LAT, Swift UVOT/XRT, NuSTAR, ASAS-SN, ZTF, Pan-STARRS, SMARTS) come from the observations table by cone search:
rows = client.observations.cone_search(ra=166.113808, dec=38.208833, radius_arcsec=10,
is_lightcurve=True, ordering="mjd_mid")
for row in rows:
print(row.catalog, row.filter_band, row.mjd_mid, row.flux, row.flux_err)
Filter with catalog=, filter_band=, mjd_min=/mjd_max= and limit=; see the
Observations guide for the catalogue codes.
Quick model curve¶
infer() computes one SSC, EIC or hadronic model curve from given parameters, synchronously:
curve = client.modeling.infer(
z=0.031, ebl=True, model_type="SSC",
parameters={"log_B": -1.5, "log_electron_luminosity": 44.0, "log_gamma_cut": 5.0,
"log_gamma_min": 2.0, "log_radius": 16.0, "lorentz_factor": 20.0,
"spectral_index": 2.2},
)
print(curve.nu, curve.nuFnu)
When all inference slots are busy the server answers 429 with Retry-After: 10; the SDK does not
retry this POST, so retry it yourself after that delay.
Fit a model to an SED¶
A fit is a batch job. Validate the file, submit it, keep the id, then wait:
from astro_mmdc import BatchJobError, PollingTimeoutError
check = client.modeling.validate_csv("mrk421.csv")
print(check.success, check.data_points)
submission = client.modeling.submit_batch("mrk421.csv", z=0.031, ebl=True, model_type="SSC")
fit_id = submission.batch_result_id
try:
result = client.modeling.wait_for_batch(fit_id, max_minutes=30)
except PollingTimeoutError:
raise SystemExit(f"still queued or running; call wait_for_batch({fit_id!r}) later")
except BatchJobError as exc:
raise SystemExit(f"fit failed: {exc.status}")
for name, p in (result.best_parameters or {}).items():
print(name, p.value, p.error)
print(result.pdf_link)
batch_infer(...) does submit and wait in one call, but waits only max_minutes=8 by default.
A fit takes from about 10–20 s (SSC) to a few minutes (EIC, HADRONIC), plus any time in the
queue, so pass a larger max_minutes when the queue may be busy. The SED CSV from
sed.to_csv() is accepted as is; keep one time period. Results are deleted 15 days after
submission. See Blazar emission modeling.
Swift UVOT/XRT analysis¶
madam.analyze() runs the Swift pipeline on a position and a time window (or obsids). A request
already covered by an earlier run answers at once from the cache; a new run downloads Swift data
and can take from minutes to hours:
job = client.madam.analyze(ra=166.1138, dec=38.2088, mjd_start=58849, mjd_end=59031,
instrument="uvot")
print(job.status, job.cached, job.count) # "done" or "no_data"
lc = [r for r in job.results or [] if r.is_lightcurve]
for row in lc:
print(row.obsid, row.filter_band, row.mjd_mid, row.flux)
Each measurement comes twice: as a light-curve row (is_lightcurve=True, mjd_mid) and as
an SED row (frequency, mjd_start/mjd_end).
instrument is "uvot", "xrt" or "swift" (both). The rows also land in the observations
table, under MMDCOUV, MMDCXRT and MMDCXRT_ORBIT. See the
Swift guide.
Raw HTTP¶
Every SDK call is plain HTTP under https://mmdc.am/api/. Without the SDK, send an
X-MMDC-Client header on every request.
SED. POST /api/sed/ with {"ra": <deg>, "dec": <deg>, "name": "<optional>"}:
curl -s -X POST https://mmdc.am/api/sed/ \
-H 'Content-Type: application/json' \
-H 'X-MMDC-Client: my-pipeline' \
-H 'Prefer: wait=25' \
-d '{"ra": 166.113808, "dec": 38.208833, "name": "Mrk 421"}'
- The answer has
id,status(queued,running,done,no_data,failed),reused,source(name,ra,dec,redshift,w_peak),job(timing,progress,events,error),links, and, once done,sed:units,catalogs, and the columnsfreq_hz,nufnu,nufnu_err,is_ul,mjd_start,mjd_end,undatedandcatalog_idx(an index intocatalogs). 200means finished (done,no_dataorfailed, witherror.codeanderror.retry_after_s).202means queued or running: sendGET /api/sed/<id>/(also withPrefer: wait=25) until the status is terminal.Prefer: wait=N(or?wait=N) holds the answer until the job ends orNseconds pass, at most 25. The server holds at most 4 such requests site-wide and 2 per client; above that it answers at once withRetry-After: 2.Preference-Appliedtells you it waited. Never assume it did: look atstatus.- Query parameters:
sed=false(source only),mjd_start,mjd_end(a point is kept when its midpoint lies in the window, ends included),undated,catalogs=NVSS,NEOWISE. GET /api/sed/<id>/?format=csvgives the CSV,GET /api/sed/jobs/<id>/the job with its progress and events.- Errors:
400witherror.fieldsfor a bad position or filter,404for an unknown id,503withRetry-After: 30when the job could not be queued.
Modeling. POST /api/modeling/inference/, /api/modeling/validate_csv/ and
/api/modeling/batch_inference/ need an identified client; poll a fit with
GET /api/modeling/batch_result/<id>/ and Prefer: wait=25.
Identification and HTTP 426¶
The modeling POSTs (inference, CSV validation, fits) accept a client that sends any of: a valid
X-API-Key, a User-Agent of astro-mmdc/0.2.4 or newer, or an X-MMDC-Client header. Anything
else gets HTTP 426 and this body (the version is the server's current minimum, also sent as the
X-MMDC-Min-Version header):
{
"error": "upgrade_required",
"reason": "unidentified",
"detail": "Unidentified clients can no longer use the MMDC modeling API. Upgrade the Python SDK: pip install -U 'astro-mmdc>=0.2.4' (optionally identify your project with MMDC(app='your-app') or an API key). For an API key or User-Agent allowlisting contact mailtommdc@gmail.com.",
"min_sdk_version": "0.2.4"
}
reason is sdk_outdated for an older SDK and invalid_api_key for a wrong key. Polling an
existing fit (batch_result) never answers 426. The SED, observations and Swift endpoints do not
require identification, but sending X-MMDC-Client everywhere costs nothing.
Limits and etiquette¶
| What | Limit |
|---|---|
Prefer: wait |
at most 25 s per request. SED: 4 waiting requests site-wide, 2 per client; fit results (batch_result): 3 site-wide, 2 per client |
| Fits queued or running at once | 2 per client without an API key; 5 or 25 with one, by tier. Above it: 429, Retry-After: 120 |
| Synchronous inference | 4 at once site-wide; above it: 429, Retry-After: 10 |
| SED reuse | any job within 2″ is reused; a failed run is not retried for 30 min unless refresh is sent |
| Fit results | deleted 15 days after submission |
- Keep at most 2 jobs in flight;
get_many()defaults tomax_concurrency=2. - On 429 or 503, wait for
Retry-Afterbefore trying again. The SDK does this for GETs and for fit submissions. - Wait with
Prefer: wait=25and send the next request right after a202; do not poll faster than once a second. - Send
refreshonly when you need data newer than the cached run, not on every request. - For an API key or a higher limit, use the contact form.
Citing¶
Cite the MMDC paper when you use MMDC data or models: Sahakyan et al. 2024, AJ, 168, 289, doi:10.3847/1538-3881/ad8231. MMDC data are licensed under CC BY 4.0 and require attribution. BibTeX and the SDK's Zenodo DOI are on Citing.