Fda Drug Adverse Event Tools#

Configuration File: fda_drug_adverse_event_tools.json Tool Type: Local Tools Count: 18

This page contains all tools defined in the fda_drug_adverse_event_tools.json configuration file.

Available Tools#

FAERS_count_additive_administration_routes (Type: FDACountAdditiveReactionsTool)#

Enumerate and count administration routes for adverse events across specified medicinal products….

FAERS_count_additive_administration_routes tool specification

Tool Information:

  • Name: FAERS_count_additive_administration_routes

  • Type: FDACountAdditiveReactionsTool

  • Description: Enumerate and count administration routes for adverse events across specified medicinal products. Only medicinalproducts is required; serious filter is optional. Use filters sparingly to avoid overly restrictive searches. Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘patient.drug.drugadministrationroute’ is recorded once per drug, NOT once per report, so a report with several drugs is counted in several rows and the rows can sum to MORE than the number of matching reports (measured for a single-product list [‘VASOPRESSIN’]: the rows sum to 9,169 against 4,676 matching reports, 196% of them). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. DO NOT use the row sum as a denominator: it counts recorded patient.drug.drugadministrationroute values, not reports. Use ‘total_reports_matching_query’ if you need one.

Parameters:

  • medicinalproducts (array) (required) Array of medicinal product names.

  • serious (string) (optional) Optional: Filter by event seriousness. Omit this parameter if you don’t want to filter by seriousness.

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_additive_administration_routes",
    "arguments": {
        "medicinalproducts": ["item1", "item2"]
    }
}
result = tu.run(query)

FAERS_count_additive_adverse_reactions (Type: FDACountAdditiveReactionsTool)#

Aggregate adverse reaction counts across specified medicinal products. Note: ‘medicinalproducts’ …

FAERS_count_additive_adverse_reactions tool specification

Tool Information:

  • Name: FAERS_count_additive_adverse_reactions

  • Type: FDACountAdditiveReactionsTool

  • Description: Aggregate adverse reaction counts across specified medicinal products. Note: ‘medicinalproducts’ is combined with OR (union) – counts are reports mentioning ANY listed product, not reports where all of them co-occur, so results for a multi-drug list can look nearly identical to the single most-reported drug’s own counts. For co-occurrence/combination-risk analysis (e.g. checking two specific drugs taken together), use FAERS_search_reports_by_drug_combination (AND) or FAERS_calculate_disproportionality instead. Only medicinalproducts is required; all other filters (patientsex, patientagegroup, occurcountry, serious, seriousnessdeath) are optional. Use filters sparingly to avoid overly restrictive searches that return no results. Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘patient.reaction.reactionmeddrapt’ is recorded once per reaction, NOT once per report, so a report with several reactions is counted in several rows and the rows can sum to MORE than the number of matching reports (measured for a single-product list [‘VASOPRESSIN’]: the first 999 ranked rows already sum to 28,818 against 4,676 matching reports, 616% of them). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. DO NOT use the row sum as a denominator: it counts recorded patient.reaction.reactionmeddrapt values, not reports. Use ‘total_reports_matching_query’ if you need one.

Parameters:

  • medicinalproducts (array) (required) Array of medicinal product names.

  • patientsex (string) (optional) Optional: Filter by patient sex. Omit this parameter if you don’t want to filter by sex.

  • patientagegroup (string) (optional) Optional: Filter by patient age group. Omit this parameter if you don’t want to filter by age.

  • occurcountry (string) (optional) Optional: Filter by country where event occurred (ISO2 code, e.g., ‘US’, ‘GB’). Omit this parameter if you don’t want to filter by country.

  • serious (string) (optional) Optional: Filter by event seriousness. Omit this parameter if you don’t want to filter by seriousness.

  • seriousnessdeath (string) (optional) Optional: Pass ‘Yes’ to filter for reports where death was an outcome. Omit this parameter to include all reports regardless of death outcome.

  • manufacturer_name (string) (optional) Filter to reports where a drug’s labeller/manufacturer matches, e.g. ‘Pfizer’. Matches openFDA’s manufacturer_name field.

  • receivedate (string) (optional) Filter by the date FDA received the report. Accepts a single date ‘YYYYMMDD’ or an openFDA range ‘[20141001 TO 20141231]’ (e.g. 2014 Q4).

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_additive_adverse_reactions",
    "arguments": {
        "medicinalproducts": ["item1", "item2"]
    }
}
result = tu.run(query)

FAERS_count_additive_event_reports_by_country (Type: FDACountAdditiveReactionsTool)#

Aggregate report counts by country of occurrence across specified medicinal products. Only medici…

FAERS_count_additive_event_reports_by_country tool specification

Tool Information:

  • Name: FAERS_count_additive_event_reports_by_country

  • Type: FDACountAdditiveReactionsTool

  • Description: Aggregate report counts by country of occurrence across specified medicinal products. Only medicinalproducts is required; all other filters (patientsex, patientagegroup, serious) are optional. Use filters sparingly to avoid overly restrictive searches. Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘occurcountry’ holds at most one value per report, but openFDA computes a count facet only over reports that record the field, so reports missing it are EXCLUDED from the rows entirely rather than bucketed as unknown and the rows sum BELOW the number of matching reports (measured for a single-product list [‘VASOPRESSIN’]: the rows sum to 3,888 of 4,676 matching reports). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. Neither figure is a population at risk, so dividing a row by either does not give a rate.

Parameters:

  • medicinalproducts (array) (required) Array of medicinal product names.

  • patientsex (string) (optional) Optional: Filter by patient sex. Omit this parameter if you don’t want to filter by sex.

  • patientagegroup (string) (optional) Optional: Filter by patient age group. Omit this parameter if you don’t want to filter by age.

  • serious (string) (optional) Optional: Filter by event seriousness. Omit this parameter if you don’t want to filter by seriousness.

  • manufacturer_name (string) (optional) Filter to reports where a drug’s labeller/manufacturer matches, e.g. ‘Pfizer’. Matches openFDA’s manufacturer_name field.

  • receivedate (string) (optional) Filter by the date FDA received the report. Accepts a single date ‘YYYYMMDD’ or an openFDA range ‘[20141001 TO 20141231]’ (e.g. 2014 Q4).

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_additive_event_reports_by_country",
    "arguments": {
        "medicinalproducts": ["item1", "item2"]
    }
}
result = tu.run(query)

FAERS_count_additive_reaction_outcomes (Type: FDACountAdditiveReactionsTool)#

Determine reaction outcome counts (e.g., recovered, resolving, fatal) across medicinal products. …

FAERS_count_additive_reaction_outcomes tool specification

Tool Information:

  • Name: FAERS_count_additive_reaction_outcomes

  • Type: FDACountAdditiveReactionsTool

  • Description: Determine reaction outcome counts (e.g., recovered, resolving, fatal) across medicinal products. Only medicinalproducts is required; all other filters (patientsex, patientagegroup, occurcountry) are optional. Use filters sparingly to avoid overly restrictive searches. Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘patient.reaction.reactionoutcome’ is recorded once per reaction, NOT once per report, so a report with several reactions is counted in several rows and the rows can sum to MORE than the number of matching reports (measured for a single-product list [‘VASOPRESSIN’]: the rows sum to 5,430 against 4,676 matching reports, so ‘Fatal’ over the row sum is NOT a case-fatality rate). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. DO NOT use the row sum as a denominator: it counts recorded patient.reaction.reactionoutcome values, not reports. Use ‘total_reports_matching_query’ if you need one.

Parameters:

  • medicinalproducts (array) (required) Array of medicinal product names.

  • patientsex (string) (optional) No description

  • patientagegroup (string) (optional) No description

  • occurcountry (string) (optional) No description

  • manufacturer_name (string) (optional) Filter to reports where a drug’s labeller/manufacturer matches, e.g. ‘Pfizer’. Matches openFDA’s manufacturer_name field.

  • receivedate (string) (optional) Filter by the date FDA received the report. Accepts a single date ‘YYYYMMDD’ or an openFDA range ‘[20141001 TO 20141231]’ (e.g. 2014 Q4).

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_additive_reaction_outcomes",
    "arguments": {
        "medicinalproducts": ["item1", "item2"]
    }
}
result = tu.run(query)

FAERS_count_additive_reports_by_reporter_country (Type: FDACountAdditiveReactionsTool)#

Aggregate adverse event reports by primary reporter country across medicinal products. Only medic…

FAERS_count_additive_reports_by_reporter_country tool specification

Tool Information:

  • Name: FAERS_count_additive_reports_by_reporter_country

  • Type: FDACountAdditiveReactionsTool

  • Description: Aggregate adverse event reports by primary reporter country across medicinal products. Only medicinalproducts is required; all other filters (patientsex, patientagegroup, serious) are optional. Use filters sparingly to avoid overly restrictive searches. Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘primarysource.reportercountry’ holds at most one value per report, but openFDA computes a count facet only over reports that record the field, so reports missing it are EXCLUDED from the rows entirely rather than bucketed as unknown and the rows sum BELOW the number of matching reports (measured for a single-product list [‘VASOPRESSIN’]: the rows sum to 4,608 of 4,676 matching reports). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. Neither figure is a population at risk, so dividing a row by either does not give a rate.

Parameters:

  • medicinalproducts (array) (required) Array of medicinal product names.

  • patientsex (string) (optional) Optional: Filter by patient sex. Omit this parameter if you don’t want to filter by sex.

  • patientagegroup (string) (optional) Optional: Filter by patient age group. Omit this parameter if you don’t want to filter by age.

  • serious (string) (optional) Optional: Filter by event seriousness. Omit this parameter if you don’t want to filter by seriousness.

  • manufacturer_name (string) (optional) Filter to reports where a drug’s labeller/manufacturer matches, e.g. ‘Pfizer’. Matches openFDA’s manufacturer_name field.

  • receivedate (string) (optional) Filter by the date FDA received the report. Accepts a single date ‘YYYYMMDD’ or an openFDA range ‘[20141001 TO 20141231]’ (e.g. 2014 Q4).

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_additive_reports_by_reporter_country",
    "arguments": {
        "medicinalproducts": ["item1", "item2"]
    }
}
result = tu.run(query)

FAERS_count_additive_seriousness_classification (Type: FDACountAdditiveReactionsTool)#

Quantify serious vs non-serious classifications across medicinal products. Only medicinalproducts…

FAERS_count_additive_seriousness_classification tool specification

Tool Information:

  • Name: FAERS_count_additive_seriousness_classification

  • Type: FDACountAdditiveReactionsTool

  • Description: Quantify serious vs non-serious classifications across medicinal products. Only medicinalproducts is required; all other filters (patientsex, patientagegroup, occurcountry) are optional. Use filters sparingly to avoid overly restrictive searches. Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘serious’ holds at most one value per report, but openFDA computes a count facet only over reports that record the field, so reports missing it are EXCLUDED from the rows entirely rather than bucketed as unknown and the rows sum BELOW the number of matching reports (measured for a single-product list [‘VASOPRESSIN’]: the rows sum to 4,676 of 4,676 matching reports, but coverage is not guaranteed for every query). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. Neither figure is a population at risk, so dividing a row by either does not give a rate.

Parameters:

  • medicinalproducts (array) (required) Array of medicinal product names.

  • patientsex (string) (optional) Optional: Filter by patient sex. Omit this parameter if you don’t want to filter by sex.

  • patientagegroup (string) (optional) Optional: Filter by patient age group. Omit this parameter if you don’t want to filter by age.

  • occurcountry (string) (optional) Optional: Filter by country where event occurred (ISO2 code, e.g., ‘US’, ‘GB’). Omit this parameter if you don’t want to filter by country.

  • manufacturer_name (string) (optional) Filter to reports where a drug’s labeller/manufacturer matches, e.g. ‘Pfizer’. Matches openFDA’s manufacturer_name field.

  • receivedate (string) (optional) Filter by the date FDA received the report. Accepts a single date ‘YYYYMMDD’ or an openFDA range ‘[20141001 TO 20141231]’ (e.g. 2014 Q4).

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_additive_seriousness_classification",
    "arguments": {
        "medicinalproducts": ["item1", "item2"]
    }
}
result = tu.run(query)

FAERS_count_country_by_drug_event (Type: FDADrugAdverseEventTool)#

Count the number of adverse event reports per country of occurrence. Only medicinalproduct is req…

FAERS_count_country_by_drug_event tool specification

Tool Information:

  • Name: FAERS_count_country_by_drug_event

  • Type: FDADrugAdverseEventTool

  • Description: Count the number of adverse event reports per country of occurrence. Only medicinalproduct is required; all other filters (patientsex, patientagegroup, serious) are optional. Use filters sparingly to avoid overly restrictive searches. Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘occurcountry’ holds at most one value per report, but openFDA computes a count facet only over reports that record the field, so reports missing it are EXCLUDED from the rows entirely rather than bucketed as unknown and the rows sum BELOW the number of matching reports (measured for vasopressin: the rows sum to 3,949 of 4,741 matching reports). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. Neither figure is a population at risk, so dividing a row by either does not give a rate.

Parameters:

  • medicinalproduct (string) (required) Drug name.

  • patientsex (string) (optional) Optional: Filter by patient sex. Omit this parameter if you don’t want to filter by sex.

  • patientagegroup (string) (optional) Optional: Filter by patient age group. Omit this parameter if you don’t want to filter by age.

  • serious (string) (optional) Optional: Filter by event seriousness. Omit this parameter if you don’t want to filter by seriousness.

  • manufacturer_name (string) (optional) Filter to reports where a drug’s labeller/manufacturer matches, e.g. ‘Pfizer’. Matches openFDA’s manufacturer_name field.

  • receivedate (string) (optional) Filter by the date FDA received the report. Accepts a single date ‘YYYYMMDD’ or an openFDA range ‘[20141001 TO 20141231]’ (e.g. 2014 Q4).

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_country_by_drug_event",
    "arguments": {
        "medicinalproduct": "example_value"
    }
}
result = tu.run(query)

FAERS_count_drug_characterization (Type: FDADrugAdverseEventTool)#

Aggregate FDA adverse event (FAERS) reports for a drug by drugcharacterization, i.e. the role the…

FAERS_count_drug_characterization tool specification

Tool Information:

  • Name: FAERS_count_drug_characterization

  • Type: FDADrugAdverseEventTool

  • Description: Aggregate FDA adverse event (FAERS) reports for a drug by drugcharacterization, i.e. the role the drug played in the report: Suspect (the drug is suspected of causing the event), Concomitant (co-administered but not suspected), or Interacting (involved in a drug-drug interaction). Answers ‘in what fraction of adverse-event reports is drug X the SUSPECT drug versus merely a concomitant/co-administered drug?’. Only medicinalproduct is required; the optional serious filter restricts to serious/non-serious reports. Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘patient.drug.drugcharacterization’ is recorded once per drug, NOT once per report, so a report with several drugs is counted in several rows and the rows can sum to MORE than the number of matching reports (measured for vasopressin: the rows sum to 8,266 against 4,741 matching reports). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. DO NOT use the row sum as a denominator: it counts recorded patient.drug.drugcharacterization values, not reports. Use ‘total_reports_matching_query’ if you need one.

Parameters:

  • medicinalproduct (string) (required) Drug name (brand or generic, e.g., ‘WARFARIN’, ‘METFORMIN’).

  • serious (string) (optional) Optional: Filter by event seriousness. Omit this parameter if you don’t want to filter by seriousness.

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_drug_characterization",
    "arguments": {
        "medicinalproduct": "example_value"
    }
}
result = tu.run(query)

FAERS_count_drug_routes_by_event (Type: FDADrugAdverseEventTool)#

Count the most common routes of administration for drugs involved in adverse event reports. Only …

FAERS_count_drug_routes_by_event tool specification

Tool Information:

  • Name: FAERS_count_drug_routes_by_event

  • Type: FDADrugAdverseEventTool

  • Description: Count the most common routes of administration for drugs involved in adverse event reports. Only medicinalproduct is required; serious filter is optional. Use filters sparingly to avoid overly restrictive searches. Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘patient.drug.drugadministrationroute’ is recorded once per drug, NOT once per report, so a report with several drugs is counted in several rows and the rows can sum to MORE than the number of matching reports (measured for vasopressin: the rows sum to 9,273 against 4,741 matching reports, 196% of them). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. DO NOT use the row sum as a denominator: it counts recorded patient.drug.drugadministrationroute values, not reports. Use ‘total_reports_matching_query’ if you need one.

Parameters:

  • medicinalproduct (string) (required) Drug name.

  • serious (string) (optional) Optional: Filter by event seriousness. Omit this parameter if you don’t want to filter by seriousness.

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_drug_routes_by_event",
    "arguments": {
        "medicinalproduct": "example_value"
    }
}
result = tu.run(query)

FAERS_count_drugs_by_drug_event (Type: FDADrugAdverseEventTool)#

Count the number of different drugs involved in FDA adverse event reports. All filters (patientse…

FAERS_count_drugs_by_drug_event tool specification

Tool Information:

  • Name: FAERS_count_drugs_by_drug_event

  • Type: FDADrugAdverseEventTool

  • Description: Count the number of different drugs involved in FDA adverse event reports. All filters (patientsex, patientagegroup, occurcountry, serious) are optional. Use filters sparingly to avoid overly restrictive searches. Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘patient.drug.medicinalproduct’ is recorded once per drug, NOT once per report, so a report with several drugs is counted in several rows and the rows can sum to MORE than the number of matching reports (measured for vasopressin: the rows sum to 71,874 against 4,741 matching reports, because every co-reported drug on a report is counted). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. DO NOT use the row sum as a denominator: it counts recorded patient.drug.medicinalproduct values, not reports. Use ‘total_reports_matching_query’ if you need one.

Parameters:

  • patientsex (string) (optional) Optional: Filter by patient sex. Omit this parameter if you don’t want to filter by sex.

  • patientagegroup (string) (optional) Optional: Filter by patient age group. Omit this parameter if you don’t want to filter by age.

  • occurcountry (string) (optional) Optional: Filter by country where event occurred (ISO2 code, e.g., ‘US’, ‘GB’). Omit this parameter if you don’t want to filter by country.

  • serious (string) (optional) Optional: Filter by event seriousness. Omit this parameter if you don’t want to filter by seriousness.

  • manufacturer_name (string) (optional) Filter to reports where a drug’s labeller/manufacturer matches, e.g. ‘Pfizer’. Matches openFDA’s manufacturer_name field.

  • receivedate (string) (optional) Filter by the date FDA received the report. Accepts a single date ‘YYYYMMDD’ or an openFDA range ‘[20141001 TO 20141231]’ (e.g. 2014 Q4).

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_drugs_by_drug_event",
    "arguments": {
    }
}
result = tu.run(query)

FAERS_count_indications_by_drug (Type: FDADrugAdverseEventTool)#

Aggregate FDA adverse event (FAERS) reports for a drug by the INDICATION (the medical condition t…

FAERS_count_indications_by_drug tool specification

Tool Information:

  • Name: FAERS_count_indications_by_drug

  • Type: FDADrugAdverseEventTool

  • Description: Aggregate FDA adverse event (FAERS) reports for a drug by the INDICATION (the medical condition the drug was being used to treat), returning the distribution of indications across all reports for that drug. Answers ‘across all adverse-event reports for drug X, what were the top conditions it was prescribed for?’. Only medicinalproduct is required; the optional serious filter restricts to serious/non-serious reports. Use filters sparingly to avoid overly restrictive searches that return no results. Note: ‘PRODUCT USED FOR UNKNOWN INDICATION’ is a common term when the prescribing indication was not reported. Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘patient.drug.drugindication’ is recorded once per drug, NOT once per report, so a report with several drugs is counted in several rows and the rows can sum to MORE than the number of matching reports (measured for vasopressin: the rows sum to 21,895 against 4,741 matching reports, because the indication of every co-reported drug is counted). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. DO NOT use the row sum as a denominator: it counts recorded patient.drug.drugindication values, not reports. Use ‘total_reports_matching_query’ if you need one.

Parameters:

  • medicinalproduct (string) (required) Drug name (brand or generic, e.g., ‘WARFARIN’, ‘METFORMIN’).

  • serious (string) (optional) Optional: Filter by event seriousness. Omit this parameter if you don’t want to filter by seriousness.

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_indications_by_drug",
    "arguments": {
        "medicinalproduct": "example_value"
    }
}
result = tu.run(query)

FAERS_count_outcomes_by_drug_event (Type: FDADrugAdverseEventTool)#

Count the outcome of adverse reactions (recovered, recovering, fatal, unresolved). Only medicinal…

FAERS_count_outcomes_by_drug_event tool specification

Tool Information:

  • Name: FAERS_count_outcomes_by_drug_event

  • Type: FDADrugAdverseEventTool

  • Description: Count the outcome of adverse reactions (recovered, recovering, fatal, unresolved). Only medicinalproduct is required; all other filters (patientsex, patientagegroup, occurcountry) are optional. Use filters sparingly to avoid overly restrictive searches. Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘patient.reaction.reactionoutcome’ is recorded once per reaction, NOT once per report, so a report with several reactions is counted in several rows and the rows can sum to MORE than the number of matching reports (measured for vasopressin: the rows sum to 5,514 against 4,741 matching reports, so 1,477 ‘Fatal’ over the row sum is NOT a case-fatality rate). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. DO NOT use the row sum as a denominator: it counts recorded patient.reaction.reactionoutcome values, not reports. Use ‘total_reports_matching_query’ if you need one.

Parameters:

  • medicinalproduct (string) (required) Drug name.

  • patientsex (string) (optional) No description

  • patientagegroup (string) (optional) No description

  • occurcountry (string) (optional) No description

  • manufacturer_name (string) (optional) Filter to reports where a drug’s labeller/manufacturer matches, e.g. ‘Pfizer’. Matches openFDA’s manufacturer_name field.

  • receivedate (string) (optional) Filter by the date FDA received the report. Accepts a single date ‘YYYYMMDD’ or an openFDA range ‘[20141001 TO 20141231]’ (e.g. 2014 Q4).

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_outcomes_by_drug_event",
    "arguments": {
        "medicinalproduct": "example_value"
    }
}
result = tu.run(query)

FAERS_count_patient_age_distribution (Type: FDADrugAdverseEventTool)#

Analyze the age distribution of patients experiencing adverse events for a specific drug. Only me…

FAERS_count_patient_age_distribution tool specification

Tool Information:

  • Name: FAERS_count_patient_age_distribution

  • Type: FDADrugAdverseEventTool

  • Description: Analyze the age distribution of patients experiencing adverse events for a specific drug. Only medicinalproduct is required. The age groups are: Neonate (0-28 days), Infant (29 days - 23 months), Child (2-11 years), Adolescent (12-17 years), Adult (18-64 years), Elderly (65+ years). Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘patient.patientagegroup’ holds at most one value per report, but openFDA computes a count facet only over reports that record the field, so reports missing it are EXCLUDED from the rows entirely rather than bucketed as unknown and the rows sum BELOW the number of matching reports (measured for vasopressin: the rows sum to 906 of 4,741 matching reports, so 81% of reports are missing from the distribution entirely). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. Neither figure is a population at risk, so dividing a row by either does not give a rate.

Parameters:

  • medicinalproduct (string) (required) Drug name.

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_patient_age_distribution",
    "arguments": {
        "medicinalproduct": "example_value"
    }
}
result = tu.run(query)

FAERS_count_reactions_by_drug_event (Type: FDADrugAdverseEventTool)#

Count the number of adverse reactions reported for a given drug. Only medicinalproduct is require…

FAERS_count_reactions_by_drug_event tool specification

Tool Information:

  • Name: FAERS_count_reactions_by_drug_event

  • Type: FDADrugAdverseEventTool

  • Description: Count the number of adverse reactions reported for a given drug. Only medicinalproduct is required; all other filters (patientsex, patientagegroup, occurcountry, serious, seriousnessdeath, reactionmeddraverse) are optional. When reactionmeddraverse is not specified, returns adverse reactions (AE) with their counts grouped by MedDRA Preferred Term, ranked by descending report count and capped at ‘limit’ terms – not the complete list. When reactionmeddraverse is specified, filters results to only include that specific MedDRA Lowest Level Term. Use filters sparingly to avoid overly restrictive searches that return no results. Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘patient.reaction.reactionmeddrapt’ is recorded once per reaction, NOT once per report, so a report with several reactions is counted in several rows and the rows can sum to MORE than the number of matching reports (measured for vasopressin: the rows sum to 29,070 against 4,741 matching reports). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. DO NOT use the row sum as a denominator: it counts recorded patient.reaction.reactionmeddrapt values, not reports. Use ‘total_reports_matching_query’ if you need one.

Parameters:

  • medicinalproduct (string) (required) Drug name.

  • patientsex (string) (optional) Optional: Filter by patient sex. Omit this parameter if you don’t want to filter by sex.

  • patientagegroup (string) (optional) Optional: Filter by patient age group. Omit this parameter if you don’t want to filter by age.

  • occurcountry (string) (optional) Optional: Filter by country where event occurred (ISO2 code, e.g., ‘US’, ‘GB’). Omit this parameter if you don’t want to filter by country.

  • serious (string) (optional) Optional: Filter by event seriousness. Omit this parameter if you don’t want to filter by seriousness.

  • seriousnessdeath (string) (optional) Optional: Pass ‘Yes’ to filter for reports where death was an outcome. Omit this parameter to include all reports regardless of death outcome.

  • reactionmeddraverse (string) (optional) Optional: Filter by MedDRA reaction term (Lowest Level Term). When omitted, returns the top-ranked adverse reactions with their counts, capped at ‘limit’. When specified, filters results to only include that specific reaction term.

  • manufacturer_name (string) (optional) Filter to reports where a drug’s labeller/manufacturer matches, e.g. ‘Pfizer’. Matches openFDA’s manufacturer_name field.

  • receivedate (string) (optional) Filter by the date FDA received the report. Accepts a single date ‘YYYYMMDD’ or an openFDA range ‘[20141001 TO 20141231]’ (e.g. 2014 Q4).

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_reactions_by_drug_event",
    "arguments": {
        "medicinalproduct": "example_value"
    }
}
result = tu.run(query)

FAERS_count_reporter_qualification (Type: FDADrugAdverseEventTool)#

Aggregate FDA adverse event (FAERS) reports for a drug by the primary-source reporter qualificati…

FAERS_count_reporter_qualification tool specification

Tool Information:

  • Name: FAERS_count_reporter_qualification

  • Type: FDADrugAdverseEventTool

  • Description: Aggregate FDA adverse event (FAERS) reports for a drug by the primary-source reporter qualification (who submitted the report): Physician, Pharmacist, Other health professional, Lawyer, or Consumer or non-health professional. Answers ‘what share of adverse-event reports for drug X came from physicians/pharmacists versus consumers/lawyers?’ - a report-quality and reliability dimension (clinician-sourced reports are generally considered more reliable). Only medicinalproduct is required; the optional serious filter restricts to serious/non-serious reports. Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘primarysource.qualification’ holds at most one value per report, but openFDA computes a count facet only over reports that record the field, so reports missing it are EXCLUDED from the rows entirely rather than bucketed as unknown and the rows sum BELOW the number of matching reports (measured for vasopressin: the rows sum to 4,603 of 4,741 matching reports). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. Neither figure is a population at risk, so dividing a row by either does not give a rate.

Parameters:

  • medicinalproduct (string) (required) Drug name (brand or generic, e.g., ‘WARFARIN’, ‘METFORMIN’).

  • serious (string) (optional) Optional: Filter by event seriousness. Omit this parameter if you don’t want to filter by seriousness.

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_reporter_qualification",
    "arguments": {
        "medicinalproduct": "example_value"
    }
}
result = tu.run(query)

FAERS_count_reportercountry_by_drug_event (Type: FDADrugAdverseEventTool)#

Count the number of FDA adverse event reports grouped by the country of the primary reporter. Onl…

FAERS_count_reportercountry_by_drug_event tool specification

Tool Information:

  • Name: FAERS_count_reportercountry_by_drug_event

  • Type: FDADrugAdverseEventTool

  • Description: Count the number of FDA adverse event reports grouped by the country of the primary reporter. Only medicinalproduct is required; all other filters (patientsex, patientagegroup, serious) are optional. Use filters sparingly to avoid overly restrictive searches. Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘primarysource.reportercountry’ holds at most one value per report, but openFDA computes a count facet only over reports that record the field, so reports missing it are EXCLUDED from the rows entirely rather than bucketed as unknown and the rows sum BELOW the number of matching reports (measured for vasopressin: the rows sum to 4,673 of 4,741 matching reports). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. Neither figure is a population at risk, so dividing a row by either does not give a rate.

Parameters:

  • medicinalproduct (string) (required) Drug name.

  • patientsex (string) (optional) Optional: Filter by patient sex. Omit this parameter if you don’t want to filter by sex.

  • patientagegroup (string) (optional) Optional: Filter by patient age group. Omit this parameter if you don’t want to filter by age.

  • serious (string) (optional) Optional: Filter by event seriousness. Omit this parameter if you don’t want to filter by seriousness.

  • manufacturer_name (string) (optional) Filter to reports where a drug’s labeller/manufacturer matches, e.g. ‘Pfizer’. Matches openFDA’s manufacturer_name field.

  • receivedate (string) (optional) Filter by the date FDA received the report. Accepts a single date ‘YYYYMMDD’ or an openFDA range ‘[20141001 TO 20141231]’ (e.g. 2014 Q4).

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_reportercountry_by_drug_event",
    "arguments": {
        "medicinalproduct": "example_value"
    }
}
result = tu.run(query)

FAERS_count_seriousness_by_drug_event (Type: FDADrugAdverseEventTool)#

Count the number of adverse event reports classified as serious or non-serious. Only medicinalpro…

FAERS_count_seriousness_by_drug_event tool specification

Tool Information:

  • Name: FAERS_count_seriousness_by_drug_event

  • Type: FDADrugAdverseEventTool

  • Description: Count the number of adverse event reports classified as serious or non-serious. Only medicinalproduct is required; all other filters (patientsex, patientagegroup, occurcountry) are optional. Use filters sparingly to avoid overly restrictive searches. In results, term Serious means: “The adverse event resulted in death, a life threatening condition, hospitalization, disability, congenital anomaly, or other serious condition”, term Non-serious means “The adverse event did not result in any of the above”. Data source: FDA Adverse Event Reporting System (FAERS). Returns an object with ‘results’ (term/count rows ranked by descending report count), ‘result_count’, the applied ‘limit’ (default 100, maximum 1000) and a ‘truncated’ flag; when ‘truncated’ is true a ‘truncation_note’ explains that more terms exist and how to request them. openFDA does not report how many distinct terms exist in total, so a term missing from a truncated list is not evidence it was never reported. COUNT SEMANTICS: ‘serious’ holds at most one value per report, but openFDA computes a count facet only over reports that record the field, so reports missing it are EXCLUDED from the rows entirely rather than bucketed as unknown and the rows sum BELOW the number of matching reports (measured for vasopressin: the rows sum to 4,741 of 4,741 matching reports, but coverage is not guaranteed for every query). The response therefore also carries ‘total_reports_matching_query’ (every report matching this query, from a separate openFDA request on the same search; null if that request fails), ‘stratified_report_count’ (what the rows shown sum to) and a ‘coverage_note’ stating which way the facet is off. Neither figure is a population at risk, so dividing a row by either does not give a rate.

Parameters:

  • medicinalproduct (string) (required) Drug name.

  • patientsex (string) (optional) Optional: Filter by patient sex. Omit this parameter if you don’t want to filter by sex.

  • patientagegroup (string) (optional) Optional: Filter by patient age group. Omit this parameter if you don’t want to filter by age.

  • occurcountry (string) (optional) Optional: Filter by country where event occurred (ISO2 code, e.g., ‘US’, ‘GB’). Omit this parameter if you don’t want to filter by country.

  • manufacturer_name (string) (optional) Filter to reports where a drug’s labeller/manufacturer matches, e.g. ‘Pfizer’. Matches openFDA’s manufacturer_name field.

  • receivedate (string) (optional) Filter by the date FDA received the report. Accepts a single date ‘YYYYMMDD’ or an openFDA range ‘[20141001 TO 20141231]’ (e.g. 2014 Q4).

  • limit (integer) (optional) Optional: maximum number of ranked terms to return (default 100, which is openFDA’s own page size for count aggregations; maximum 1000, openFDA’s documented ceiling). Terms are ranked by descending report count, so a small limit hides the long tail – a term absent from the response is NOT evidence that it was never reported. The response sets ‘truncated’ and adds a ‘truncation_note’ whenever more terms exist beyond the limit. Values above 999 require an openFDA API key in the FDA_API_KEY environment variable.

Example Usage:

query = {
    "name": "FAERS_count_seriousness_by_drug_event",
    "arguments": {
        "medicinalproduct": "example_value"
    }
}
result = tu.run(query)