Search by tag

List of arguments

The list of arguments for running a search by tag can be found at https://api.lsst.fink-portal.org . The schema of the returned payload can be found on the schema page and you can also retrieve it programmatically.

Default class search

What is a class in Fink?

We recommend to read how the classification scheme is built.

To facilitate the identification of noteworthy events, users can create filters that combine multiple alert fields, allowing them to generate meaningful tags tailored to their research needs. These tags are available to anyone, and you can easily search alerts by tag:

PythoncurlwgetQuery URL

import io
import requests
import pandas as pd

# Get latests 5 alerts reported to TNS
r = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/tags",
  json={
    "tag": "in_tns",
    "columns": "r:diaObjectId",
    "n": "5"  # (1)!
  }
)

# Format output in a DataFrame
pdf = pd.read_json(io.BytesIO(r.content))

This the maximum number of alerts to retrieve. It can lead to several times the same object though.

# Get latests 5 alerts reported to TNS
curl -H "Content-Type: application/json" -X POST \
    -d '{"tag":"in_tns", "n":"5"}' \
    https://api.lsst.fink-portal.org/api/v1/tags -o latest_five_in_tns.json

# you can also specify parameters in the URL, e.g. with wget:
wget "https://api.lsst.fink-portal.org/api/v1/tags?tag=in_tns&n=5&output-format=json" \
    -O latest_five_in_tns.json

Paste this query on your browser to see results:

https://lsst.fink-portal.org/?action=tag&tag=in_tns&last=5

You can also easily list the available tags by pasting this into your browser:

Dictionary of tags and their documentation

https://api.lsst.fink-portal.org/api/v1/tags

Class search restricted in time

You can also specify startdate and stopdate for your search:

Restrict time boundaries

import io
import requests
import pandas as pd

# Get all alerts reported in TNS between December 10th 2025 and December 31st 2025
r = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/tags",
  json={
    "tag": "in_tns",
    "n": "100", # (1)!
    "startdate": "2025-12-10",
    "stopdate": "2025-12-31"
  }
)

# Format output in a DataFrame
pdf = pd.read_json(io.BytesIO(r.content))

This the maximum number of alerts to retrieve. There could be more or less than n in the specified period.

Retrieving full object data

Note that only alerts that pass the criterion of a tag are stored in the corresponding tag table. But for a given object, not necessarily all alerts would satisfy the criteria. Therefore, you will not access the full lightcurve for each object through this endpoint.

Hence, if you need to query all the alert data for objects found with a tag search, or additional data that is not available in the tag table, you would do it in two steps:

Retrieve full lightcurve for objects found in tag search

r0 = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/tags",
  json={
    "tag": "in_tns",
    "n": "10",
    "columns": "r:diaObjectId" # (1)!
  }
)

mylist = [str(val["r:diaObjectId"]) for val in r0.json()]

# get full lightcurves for all these alerts
r1 = requests.post(
  "https://api.lsst.fink-portal.org/api/v1/sources",
  json={
    "diaObjectId": ",".join(mylist),
    "columns": "r:diaObjectId,r:midpointMjdTai,r:psfFlux,r:psfFluxErr", # (2)!
    "output-format": "json"
  }
)

# Format output in a DataFrame
pdf = pd.read_json(io.BytesIO(r1.content))

Select only the column you need to get faster results!
Select only the column(s) you need to get faster results!