Report-Specific API Parameters

Report-specific API parameters let you filter the data you retrieve from a COMET Data report. They are the same filters you see on the report form in COMET Data, such as Registration start date from. You add them to the API URL to retrieve only the records you need, for example, a single person or a single date range.

The filters are applied in the same way as when you run the report on screen. API calls return only the data you request and run as quickly as the report does in COMET Data.

Authorizations

Before you start, make sure that:

1. You have been granted access to the COMET Data API.

2. The report is saved in My Reports. To learn how to save a report and generate its API code, see API Access to COMET Data.

The data an API URL can return depends on the active profile of the user who created the API code. We recommend creating API codes with a user who has only one profile.

Filtering

An API call can use filters from two places:

• Filters saved in the report. These are the filters that were set when the report was saved in My Reports. They apply to every call made with that API code.

• Filters added to the URL. You can add these to any call to further narrow the results.

The two sets are combined. If the same filter is both saved in the report and added to the URL, the value in the URL is used. For example, say the saved report has Registration start date from set to 1 January 2026. If the URL contains RegistrationStartDateFrom=2026-06-01, the call uses 1 June 2026 instead.

You can only use the filters that are on that report's form. To filter by an ID, the report must have a matching filter. For example, if the report has a Person ID filter, PersonId=12345 returns only that person's records.

The system checks every filter, both saved and added, against the access of the user who created the API code. If any filter asks for data outside that access, the call is refused. You get nothing back, not even partial data. This protects data that the user who shared the API code is not allowed to see. See Access Rules for COMET Data.

Step-by-step guide

How to copy an API URL with filters

This is for users with access to the COMET Data API.

1. In COMET Data, go to My Reports.

2. Click the saved report.
   The report form opens with the saved filters already filled in.

3. Change the values of existing filters or add new ones.

4. Click Copy API Code.
   The URL is copied to your clipboard. It contains your API key and every filter you changed compared to the saved report.

5. Paste the URL wherever you need it, for example, in an email to an external developer.

Calls made with this URL use the filters saved in the report plus the ones you changed. The saved report itself stays as it was.

If you don't see Copy API Code, you have not been granted COMET Data API access.

Add or change filters in the API URL

This is for anyone using the API URL, for example, an external developer.

1. Start from the API URL for the report, for example:
   https://<comet-url>/data-backend/api/public/areports/run/0/25/?API_KEY=XXXX

2. For each filter, add & followed by the filter name, = and the value, for example:
   …?API_KEY=XXXX&PersonId=12345

3. To change a value saved in the report, add the same filter with the new value. The URL value is used instead of the saved one.

4. Run the call.
   The response contains only the matching records and lists all filters that were applied. See What you get back below.

For the correct filter names and how to write each value type, see Parameter names and value formats below. If the results are not what you expected, see Troubleshooting.

Parameter names and value formats

Filter names

• Each filter name matches the filter's label on the report form, written as one word with each word capitalized. For example, Registration start date from becomes RegistrationStartDateFrom.

• Names always start with a capital letter.

• Names are case-sensitive. registrationStartDateFrom is not recognized and is ignored.

The only exception is changedAfter, which keeps its name and format: a date and time in UTC, written as YYYYMMDDHHmmSS. See Generic API Parameters.

Value formats

Filters that offer a fixed list of options on the form also take IDs. For example, Organization type uses 10 for Association, 60 for Club, 70 for Stadium, and 210 for Intermediary agency.

"Copy API Code" options compared

COMET Data has two options with almost the same name. They copy different URLs:

Both URLs use the same API code. Deleting the report from My Reports stops both of them from working.

What you get back

Applied filters

In addition to the report data, the response lists every filter applied to the call. This includes the filters saved in the report and the ones added to the URL. Each entry shows the filter name, for example, PersonId or RegistrationStartDateFrom, and the value used. Depending on the filter, the value is:

• a single ID or a list of IDs

• true or false

• a date

• text

Filters that were ignored do not appear in this list.

Dates in this list use the time zone and date format of your organization's COMET system. This also applies to changedAfter, even though you send it in UTC.

For the rest of the response, such as columns, results, and paging, see API Access to COMET Data.

When access is refused

If any filter, saved or added, requests data beyond the access of the user who created the API code, the call returns 403 Forbidden with a message explaining why. No data is returned.

Key rules and limitations

Filters in the URL never change the saved report. They only apply to that call.

The usual API limits still apply: at most 10 calls per second and 1000 results per page. See API Access to COMET Data.